Install CLI + Skill

The command-line interface (CLI) runs Sovran commands in your terminal. The included sovran skill teaches an AI agent how to use those commands. Both use the same request and result rules as the API.

Open Install CLI + Skill for copy controls and setup steps. Follow the steps below to set up the CLI and then add the skill to your agent.

1. Install the CLI

Node.js 22 or later is required. Install version 0.3.0:

pnpm add -g @sovran-ai/cli@0.3.0

2. Create an API key

Open API Playground. Create a key with Read permission. Copy and store its secret before you close the secret panel.

Accepted members of an active paid workspace can use their own key. Each operation keeps the dashboard's owner and admin checks. Read is required. Content setup needs Write. Generation and finished exports need Generate. Deletion needs Delete.

3. Set the key and host

Set SOVRAN_API_KEY through your environment or secret store. It contains the saved key secret. Keep it out of command arguments, source control, and logs.

SOVRAN_API_ORIGIN selects the host. It defaults to https://sovran.ai. Use the origin shown in API Playground. A development host has its own keys and workspace data. Do not use a production key against another host.

export SOVRAN_API_ORIGIN="https://sovran.ai"
# Set SOVRAN_API_KEY through your environment or secret store.

Use --origin http://localhost:3000 to select a local host for one command.

4. Check installation and access

sovran --version
sovran api call get__projects --query limit=10

The version command should print 0.3.0. Version 0.3.0 includes Audience variations, Creative Copilot text styles, multi-format Builds, and batch draft Render. Earlier versions reject these inputs before they reach Sovran. It does not need a key. The project request checks your key and host. An empty workspace returns data.items: []. A workspace with projects returns those records.

If the host returns api_disabled, check host availability in API Playground. If authentication fails, check the key's host, status, and Read permission.

5. Locate the complete skill

sovran skill path

This command prints the portable sovran skill folder included with the CLI. It does not install the skill. Keep the full folder, including SKILL.md, references, LICENSE, and THIRD_PARTY_NOTICES.txt.

6. Install the skill for your agent

This command copies the full folder to ~/.agents/skills/sovran. It stops if that destination already exists:

(
  set -eu
  skill_source="$(sovran skill path)"
  skill_destination="$HOME/.agents/skills/sovran"
  if [ -e "$skill_destination" ] || [ -L "$skill_destination" ]; then
    printf '%s\n' 'A Sovran skill already exists. Check it before replacing it.' >&2
    exit 1
  fi
  mkdir -p "$HOME/.agents/skills"
  cp -R "$skill_source" "$skill_destination"
)

For another agent, use that agent's documented skill directory. Change skill_destination and the mkdir path together. Keep the existing-folder check. Check an existing skill before replacing it.

7. Check the skill in your agent

Make the CLI environment available to your agent. Start a new agent session so it can load the installed skill. Ask:

Use the Sovran skill to list my projects.

The agent should discover and call the project-list operation. This first check needs Read permission and does not create content. An empty project list is a valid result.

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 jobs wait "$JOB_ID_1" "$JOB_ID_2" "$JOB_ID_3"
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. Pass up to 15 job IDs, such as every ID in a Voiceover Remix jobIds; the result lists one job per ID. Only full success of every job 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.

Batch video workflows

Use sovran api describe OPERATION_ID before each new operation. Use sovran api call with returned IDs and exact request files. These workflows use the same operations through API, CLI, and MCP.

Sequence batches permit 1–100 finished outputs. Copilot hook counts are "auto", 3, 4, 5, or 6. Copilot Video Variations counts are 4, 6, or 8. Voiceover Remix uses draftsPerVoiceover: 1, 3, or 5, with at most 15 drafts. B-roll uses draftsPerHook: 1, 3, or 5. Saved text can select 1–3 hooks. A request for two finished videos does not permit a draft-count value of 2.

Native Smart Variations accepts draftCount: 5, 10, or 20. A run can return fewer complete drafts. Poll the public jobId from acceptance. Read the saved run with its native id as resourceId. Smart sequence analysis and native Smart drafts are separate workflows. See the Smart Variations guide.

Sequence batches can include plain combinations and compatible saved row edits. The server uses the current caller's saved mappings and checks editor revisions and settings again. Edited selections permit at most one music track and one voiceover. Use a fresh estimate after mapping or revision changes. Export other compositions separately.

Copilot, native Smart Variations, and remix creation save editable drafts. Read the public creation job's outputEditorProjectIds. Render up to ten selected drafts in one batch with the draft render operations above. To export one draft at a time, read get__compositions_compositionId, estimate through post__compositions_compositionId_render_estimate, then submit through post__compositions_compositionId_renders. Each composition request exports one video. Use its current updatedAt as expectedUpdatedAt. Keep the same export settings and the returned planFingerprint.

Save a separate token before each submission. Keep its exact operation, path, query, and body. Replay that request and token after an unknown result. Poll only the accepted job. Read each ready renderId with get__renders_renderId_outputs. The URL expires at expiresAt. Read outputs again to get a fresh link. Do not submit another render for link expiry.

Smart rejection reads retain saved decisions and asset references. Missing saved references return assets: []. Voiceover history, rename, saved batch retry, and named Voiceover cleanup exclude B-roll. Generic draft and auto-edit cleanup still support both. Saved Voiceover retries resume at most two failed native jobs per request, with three retries per job, one active retry per project, and at least one minute between requests. Sequence exports permit three explicit retries. Composition export chains permit the original request and two explicit retries. Closing a local wait does not cancel accepted work.

Voiceover Remix supports either post__jobs_jobId_retry with its original public job ID or post__projects_projectId_voiceover_remix_batches_resourceId_retry with its saved batch ID. Both use {} and resume the same checkpoint. Read the batch's retryStatus first. retryAllowed: true on a public job does not prove that cooldown and other batch checks pass. Choose one route per failure. The public route returns the same public jobId for polling. The named route returns native jobIds for the batch read. B-roll creation and native Smart drafts reject generic job retries. Save a separate token for the selected retry. Do not call both routes for the same failure.

See the sequence batch guide and creation guide for lookup IDs, revision checks, retry eligibility, and separate draft exports. The packaged skill's video and draft rendering references have the same workflow steps. These instructions describe supported operations. They do not prove that a particular live batch completed.

Skill contents and updates

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. To connect an AI assistant through the hosted server, follow the MCP Server guide.