generated: '2026-09-11'
method: searched
source: https://github.com/JOYLINK-LTD/lacuna-toolkit/blob/main/packages/cli/README.md
name: lacuna
package: lacuna-toolkit
version: 0.3.4
published: '2026-08-10'
license: MIT
requires: Node.js 18 or newer, plus an API key on a Pro plan or above
install:
  - method: npx
    command: npx lacuna-toolkit --help
  - method: npm
    command: npm install -g lacuna-toolkit
  - method: pnpm
    command: pnpm add -g lacuna-toolkit
credential_resolution:
  order:
    - --api-key flag
    - LACUNA_API_KEY environment variable
    - ~/.lacuna/config.json (mode 0600)
commands:
  - group: config
    commands:
      - name: config set-key
        description: Store a lyr_live_ API key in the local config file.
      - name: config set-base-url
        description: Point the CLI at a different API host.
      - name: config show
        description: Show current config; the API key is masked.
      - name: config clear
        description: Remove the stored config.
  - group: music
    commands:
      - name: music generate
        description: Submit a generation task; optionally block until it is terminal.
        maps_to: openapi/lacuna-music-openapi-original.json#createGeneration
        flags:
          - {flag: --style, required: true, description: Style description.}
          - {flag: --title, required: true, description: Track title.}
          - {flag: --lyrics, description: Inline lyrics.}
          - {flag: --lyrics-file, description: Read lyrics from a UTF-8 file.}
          - {flag: --instrumental, description: Generate an instrumental track.}
          - {flag: --model, values: [aether, echo], default: aether}
          - {flag: --vocal-gender, values: [m, f], description: aether only.}
          - {flag: --negative-tags, description: aether only.}
          - {flag: --style-weight, description: 0-1, aether only.}
          - {flag: --weirdness-constraint, description: 0-1, aether only.}
          - {flag: --audio-weight, description: 0-1, aether only.}
          - {flag: --wait, description: Poll until the task reaches a terminal state.}
          - {flag: --poll-interval, default: 5, description: Seconds between polls with --wait.}
          - {flag: --timeout, default: 600, description: Seconds before giving up with --wait.}
          - {flag: --output, values: [json, table], default: table}
      - name: music get
        description: Read the current state of a task by id.
        maps_to: openapi/lacuna-music-openapi-original.json#getGeneration
      - name: music wait
        description: Block on a task id until it is ready or failed.
        maps_to: openapi/lacuna-music-openapi-original.json#getGeneration
exit_codes:
  - code: 2
    meaning: '--wait was set and the task ended in `failed` state.'
flows:
  - name: Generate and wait in one shot
    command: |
      lacuna music generate --style "synthwave, retro drums, 110 bpm" --title "Neon Drive" --instrumental --wait --output json
  - name: Pull audio URLs out of a finished task
    command: lacuna music get cm123abc --output json | jq '.tracks[].audio_url'
currency:
  checked: '2026-09-11'
  registry: npm
  package: lacuna-toolkit
  latest: 0.3.4
  published: '2026-08-10'
  note: >-
    The CLI ships from the same monorepo as the SDK and MCP server and versions in lockstep with them.
    No command surfacing the GET /v1/me account operation appears in the published command list, so the
    CLI — like the SDK and the hosted MCP server — has not yet caught up with the contract.