CLI and agent skill

The sovran command uses the same request and result contracts as the API. It exposes all current operations. It also provides resumable uploads, bounded job waits, and single-file downloads. Node.js 22 or later is required.

Install version 0.1.0 from the npm registry:

pnpm add -g @sovran-ai/cli@0.1.0
sovran --version
sovran --help

Set SOVRAN_API_KEY through your environment or secret store. The default host is https://sovran.ai. Use SOVRAN_API_ORIGIN or --origin http://localhost:3000 for a different host. Do not use a production key against another host.

Discover and call

sovran api list --search project
sovran api describe post__projects
sovran api call get__projects --query limit=10

Save this body as project.json:

{"name":"CLI example"}

Save a request token once before sending the change:

node -e 'require("node:fs").writeFileSync("project.token",require("node:crypto").randomUUID(),{flag:"wx",mode:384})'
sovran api call post__projects --body @project.json --idempotency-key "$(cat project.token)"

Repeat --path name=value or --query name=value for different parameters. Use --body - for JSON on standard input. The CLI validates the body without changing it. A general call sends once. Preserve the token and body after an uncertain result.

API results keep { data, requestId } on standard output. Progress and structured errors use standard error. Exit codes are 0 success, 1 API/transport/file error, 2 invalid input, 3 invalid server result, 4 incomplete workflow, and 130 cancellation.

Media tasks

sovran assets upload --project-id "$PROJECT_ID" --type video --file clip.mp4 --state clip-state.json
sovran jobs get "$JOB_ID"
sovran jobs wait "$JOB_ID" --timeout-ms 300000
sovran renders download "$RENDER_ID" --aspect-ratio 9:16 --out finished.mp4

Asset uploads also support music and image. They wait for preparation by default. Use --no-wait to return after completion. Keep the private state file. Recovery must use the same key, host, file content, and options. Expired credentials stop the upload; the CLI does not create another reservation automatically.

Voice samples use voice-clones upload with explicit consent options. This transfers the sample. Start cloning with a separate API call. See creation tools for the API rules.

Job waits handle all declared states. Only full success returns exit 0. A timeout, partial success, or review state requires inspection. Waiting does not resubmit work. Canceling a local command does not cancel a remote job.

Downloads require an output path and select one file. They obtain fresh signed URLs. They stream data without sending the API key to Storage. They do not overwrite files or retry transfers automatically. Use sovran --help for asset, voice-preview, and avatar-image downloads.

Agent skill

sovran skill path prints the included portable sovran skill directory. Copy that complete folder into your agent's skill directory. Check an existing skill before replacing it.

The skill teaches operation discovery, separate video steps, voice consent, request tokens, and recovery. It uses current CLI schemas instead of a copied operation list. It does not expand the user's authority for charges, deletion, or publishing.

The CLI and skill use a proprietary license. The packaged LICENSE permits personal and business use, including agents that act within your authority. Keep LICENSE and THIRD_PARTY_NOTICES.txt when you copy the complete, unmodified skill folder. Read these files for the use limits and third-party terms.

Installed CLI versions contain their own contracts. Upgrade to a new package release for new API operations. The API reference and CLI discovery are built from the same catalog. MCP support will be added separately.