Official Callirra CLI for multimodal chat, prompt polish, images, video, speech, music, sound effects, asset collections and Constellation workflows. One API key, Node.js 22+, JSON output, bounded polling and local binary downloads.
npm install -g @callirra/cli
callirra --help
callirra --json doctor --offlineCreate an API key at callirra.com/api. Set CALLIRRA_API_KEY=sk-cal-..., or save a key with callirra setup-api-key <key>. Authentication precedence: --api-key, environment, ~/.config/callirra/api_key. Prefer environment/config over flags to keep keys out of shell history. The default base is https://api.callirra.com; override with CALLIRRA_API_BASE or --api-base.
callirra --json doctor
callirra capabilities
callirra models
callirra models chat
callirra models audio
callirra balanceChat and Constellation require an eligible paid plan. Current model IDs, customer prices, voice lists, native media support and restrictions come from discovery responses.
callirra sessions create --title "Product review"
callirra upload ./product.png
callirra chat "Describe this product" --session <session-id> --model gpt-6-1-sol \
--request-id product-review-20261024-01 --attachment <upload-assetId> --wait --out reply.txt
callirra sessions messages <session-id> --limit 20
callirra runs get <run-id>Use upload response assetId for chat attachments; id is the storage reference ID. A session retains conversation history across turns. --attachment and --file can be repeated. --file ./clip.mp4 uploads directly; --parts-file parts.json accepts these parts:
[
{"type":"text","text":"Compare these references."},
{"id":"owned-image-asset-id","role":"reference","mediaType":"image"},
{"file":"./reference.wav"}
]Select a model whose live capabilities support your media. Some models analyze video frames; audio metadata inspection is distinct from native audio input. Upload once and use the returned asset IDs for repeatable submissions. --file may create another upload on retry, so resume an accepted run using its ID.
chat context --session <id> --model <id> <instruction> previews context usage. runs events <id> collects bounded SSE snapshots into one JSON response. runs pending reads/resumes existing pending billing. polish allowance, polish quote --body-file draft.json and polish create --body-file approved.json expose refine/adapt prompt polish, including expected credit guards.
callirra audio models
callirra audio quote --model kokoro-82m --mode tts --text "Hello from Callirra."
callirra audio create --model kokoro-82m --mode tts --text "Hello from Callirra." \
--request-id speech-20261024-01 --quote-id <quote-id> --expected-credits <quoted-credits> \
--wait --out speech.mp3
callirra audio list --request-id speech-20261024-01
callirra audio get <job-id>
callirra audio download <job-id> --index 0 --out speech.mp3Quotes expire after five minutes and bind exact settings. Speech uses text/voice; music and SFX use prompt plus the parameters advertised by audio models. --body-file accepts every native audio field. audio list --limit accepts 1–60 jobs per page (default 20); follow the returned cursor with --cursor. When billing_status is awaiting_payment, inspect credits_required and explicitly authorize additional credits with audio settle <id> --maximum-credits <approved-maximum>. Polling never pays automatically.
callirra gen image "A cinematic product photograph" --model nano-banana-2 --out hero.png
callirra gen video "A drone shot over mountains" --model seedance-2.5 --duration 10 --wait --out clip.mp4
callirra videos --limit 20
callirra task <job-id>
callirra download <job-id> --out clip.mp4
callirra upload ./reference.mp4 --content-type video/mp4 --collection-id <id>gen image supports reference URLs, size, resolution, quality, background, seed and output format. gen video supports mode, aspect ratio, audio, image/video/audio references, model modes and last-frame options. Supply --body-file settings.json for every API field; direct flags override matching fields. --out saves the first image or selected audio output as binary bytes. Asynchronous generation needs --wait when saving output.
callirra collections create --name "Product launch"
callirra assets list --collection-id <id> --limit 20
callirra assets get <asset-id>
callirra assets update <asset-id> --body '{"favorite":true}'
callirra assets download <asset-id> --out result.mp4
callirra workflows catalog
callirra workflows create --body-file project.json
callirra workflows quote --body-file graph.json
callirra workflows run <project-id> --body-file approved-run.json --wait
callirra workflows status <run-id>project.json contains {name,graph,requestId?}. Workflow graphs use the live catalog's nodes, ports and configuration fields. A reviewed run body contains {requestId,graphHash,maximumCredits,targetNodeId?}. maximumCredits limits run credits. Updates require {name,graph,revision}. workflows plan proposes graph changes without executing them; workflows tool runs supported transforms over owned assets.
| Family | Actions |
|---|---|
| Account/discovery | doctor, capabilities, `models [chat |
| Conversation | sessions list/create/get/update/delete/messages, chat, chat context, runs get/wait/cancel/events/pending |
| Prompt polish | polish allowance/quote/create |
| Audio | audio models/quote/create/list/get/wait/download/settle |
| Media | gen image/video, videos, task, cancel, download, upload |
| Assets | assets list/get/create/update/organize/delete/delete-batch/download |
| Collections | collections list/create/update/delete |
| Workflows | workflows catalog/list/get/create/update/delete/quote/run/runs/status/wait/cancel/plan/plan-status/tool |
| Knowledge | recipes, recipe <slug>, scenes [slug], creative |
| Escape hatch | request GET /v1/path, explicit POST/PATCH/PUT/DELETE with JSON input |
recipes, recipe and scenes read bundled snapshots offline. Snapshot credit figures are historical; use live discovery/quotes for current prices. The retired built-in template endpoints are not used.
All API commands emit exactly one JSON value to stdout. --json makes it compact; default JSON is pretty printed. API envelopes are preserved (for example {run}, {job}, {assets,total,next_cursor}). Downloads add a local path. Help/version are plain text. Errors emit {"error":{"message":"...","status":401,"code":"...","request_id":"..."}} to stderr with exit code 1; optional fields appear when supplied by the API. Credentials are redacted.
Use --limit for bounded lists and pass the response cursor as --cursor; message history uses --before. --timeout is seconds (1–3600, default 900), --interval is seconds (default 2). Waits stop on terminal status or pending payment. A timeout after submission includes the existing run ID and resume command.
Paid submissions are never automatically retried. Save caller request IDs and identical settings before durable chat, polish, audio and workflow submissions. Read existing status/history after a network failure. Image/video creation has no idempotency guarantee; inspect usage/history before choosing to submit again. Deletions and additional settlement only happen through their explicit named commands.
pnpm --filter @callirra/client build
pnpm --filter @callirra/cli build
pnpm --filter @callirra/cli test
pnpm --dir packages/cli link --globalThe built package locates its recipe data relative to the installed module and runs from any working directory. MIT. Source · MCP · Agent skill.
In this public repository, run npm install, npm run build, then npm test. The workspace-filter commands in the maintainer notes refer to the private monorepo; a standalone checkout uses the published @callirra/client dependency.