Spiro CLI

@spiroai/cli is the standalone command-line companion for a personal Spiro developer token. It connects only to the authenticated Spiro developer API over HTTPS; it never receives Kie, fal.ai, ElevenLabs, database, storage, or GitHub credentials.

Install and sign in

Install Node.js 20 or newer, then run:

npm install -g @spiroai/cli

In the Spiro web app, open Connect, create a personal developer token, and copy it while the one-time dialog is open. Then sign in and inspect your connection:

spiro login --endpoint https://spiroai-nwdzjgus.manus.space --token YOUR_SPIRO_DEVELOPER_TOKEN
spiro me
spiro models
spiro jobs

The token is stored locally in ~/.config/spiro/config.json using owner-only filesystem permissions. Revoke it from Connect at any time. Never paste a provider key into the CLI or a chat.

Cost-safe workflow

Every generation command first creates a no-spend proposal. Spiro shows an exact price only for verified model configurations, and no provider job is sent until you explicitly confirm the proposal.

# Images — default model: Kie • GPT Image 2
spiro image --prompt "A horse running through a misty field" --quality 1K --aspect 16:9

# Video — default model: Kie • Kling 3.0
spiro video --prompt "Slow cinematic push-in on the horse" --duration 5 --resolution 720p --aspect 16:9

# Audio and Script Planner are safe proposals.
spiro audio --script "Welcome to the launch." --model "ElevenLabs • Eleven v3" --voice-clone 123
spiro plan --script "Paste the ad script here..." --direction "Clean product B-roll" --ad-format "9:16 social" --broll-skill "UGC"

For a model configuration with a verified exact price, inspect the quote and then run:

spiro confirm <proposal-handle> --yes

Currently confirmable configurations are the active Kie Image/Video configurations shown by spiro models, subject to the exact quoted settings. Video and audio reference inputs whose pricing depends on source duration remain proposal-only rather than receiving an estimated or invented price.

Local references and exports

For image or video work, a local path is uploaded only when you explicitly pass a reference flag. Spiro validates the file again on its server, stores it privately, and returns an opaque ast_… handle; neither the CLI nor the developer API prints a storage URL.

spiro reference upload ./product.png
spiro image --model "Kie • GPT Image 2" --prompt "Make this product look premium" --quality 1K --reference ./product.png
spiro video --model "Kie • Kling 3.0" --prompt "Animate this product" --duration 5 --resolution 720p --reference ./product.png

# Seedance 2.0 / 2.5 — typed multimodal proposal inputs
spiro video --model "Kie • Seedance 2.5" --prompt "Match the product, motion, and rhythm" \
  --reference-image ./product.png --reference-video ./motion.mp4 --reference-audio ./beat.wav

The local-file flow accepts JPEG, PNG, WebP, MP4, WebM, MOV, MP3, and WAV files up to 50 MB. --reference remains the image/frame workflow. Seedance 2.0 and 2.5 also accept explicit --reference-image, --reference-video, and --reference-audio inputs. Their typed video/audio routes are proposal-only until Spiro can quote every source-duration and audio billing dimension exactly.

After a job completes, export its opaque asset handle directly to a local folder:

spiro export <asset-handle>

# Or choose a different local folder.
spiro export <asset-handle> --to ./Downloads