> For the complete documentation index, see [llms.txt](https://docs.avastudio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avastudio.com/api-and-mcp/cli.md). # Ava Studio CLI Use Ava Studio from your terminal with [`@hologramlabs/ava-cli`](https://www.npmjs.com/package/@hologramlabs/ava-cli). The command is `avastudio`: research, draft, manage campaigns, generate media, edit projects and export with the same tools as the API and MCP. ### Install Requires **Node.js 22.14 or newer**. Bun and access to Ava's source repository are not required. ```bash npm install -g @hologramlabs/ava-cli avastudio --version avastudio --help ``` This guide targets CLI **0.1.3**, supporting API contract **0.8.0** and its 76 tools, including [the project planner](/api-and-mcp/project-agent.md). The original 0.1.0 release supports contract 0.5.0. The CLI installs its SDK dependency automatically; there is no separate spec package to install. ### Sign in with an API key 1. In Ava Studio, open **Settings > Developers** and create an API key. A paid plan is required. 2. Keep **Read only** for the first account check. Choose **Custom** and enable **Research** or **Write drafts** before running those examples below. Other commands name their required permissions in the [tool reference](/api-and-mcp/tools.md). 3. Set a monthly credit budget for scripts or agents that can spend. 4. Copy the key and run: ```bash avastudio login avastudio whoami ``` `login` asks for the key without displaying it, checks it, and saves it to `~/.ava/config.json` with restricted file permissions. For CI or a script, set `AVA_API_KEY` through your secret manager instead. In Bash, you can set it without putting the key in shell history: ```bash read -rs AVA_API_KEY && export AVA_API_KEY avastudio whoami ``` The CLI also accepts a key from standard input with `avastudio login --api-key-stdin`. Use environment variables or the hidden prompt rather than `--api-key`, which puts the key in command history. ### Find a command ```bash avastudio tools avastudio brand list avastudio models --kind video avastudio research --help avastudio draft briefs --help ``` `tools` lists the tools your key can call. Every command has `--help`, including its inputs and examples. Most API names map to command groups, such as `research_trends` → `research trends`. Some use a more natural command name: `export_render` is `project export`. | Task | CLI command | API tool | | ------------------- | ---------------------------- | ------------------ | | Check the account | `avastudio whoami` | `whoami` | | List brands | `avastudio brand list` | `brand_list` | | Find trends | `avastudio research trends` | `research_trends` | | Draft briefs | `avastudio draft briefs` | `draft_briefs` | | Run a campaign plan | `avastudio plan run` | `plan_run` | | Produce a concept | `avastudio creative produce` | `creative_produce` | | Generate a scene | `avastudio scene generate` | `scene_generate` | | Export a project | `avastudio project export` | `export_render` | | Check a job | `avastudio jobs get` | `jobs_get` | ### Research and draft After enabling **Research**, ask what is trending. This uses credits: ```bash avastudio research trends "protein snacks" --limit 5 ``` Get a brand id from `avastudio brand list`. With **Write drafts** enabled, replace `YOUR_BRAND_ID` and draft one brief: ```bash avastudio draft briefs YOUR_BRAND_ID --count 1 --wait \ --idempotency-key launch-brief-001 ``` `--wait` follows the job and prints its result. The briefs appear in the brand's **From your agent** campaign in Ava Studio. Drafting makes concepts; producing media from campaign concepts is a separate operation with its own permissions and charges. Use a new idempotency key for each new action. Reuse the example key only to retry the same action with the same input. ### Follow a long-running job Without `--wait`, a long-running command returns a job id. Save it, then check it with: ```bash avastudio jobs get YOUR_JOB_ID --wait --timeout 1200 ``` `--timeout` and `--interval` use **seconds**. Most commands wait up to 600 seconds by default and poll every 2 seconds; some media commands have longer defaults, shown in `--help`. If your terminal disconnects or the wait times out, the server's job can keep running. Check the saved job id before starting another action. See [Jobs, retries and errors](/api-and-mcp/jobs-retries-and-errors.md). ### Use the CLI in scripts Use `--json` for the tool's JSON output. For a long-running command with `--wait`, this is the final job; its `result` holds the tool's output. Progress and hints go to stderr: ```bash avastudio brand list --json > brands.json avastudio research trends "protein snacks" --limit 5 --json > trends.json ``` `--quiet` prints only the essential value, such as a job id or URL. For example, with **Produce media** enabled, export an existing project and save its URL: ```bash avastudio project export YOUR_PROJECT_ID --wait --quiet \ --idempotency-key launch-export-001 > export-url.txt ``` Commands accept `--input` for raw tool input as JSON. Explicit flags override the corresponding fields: ```bash avastudio research trends --input '{"niche":"protein snacks","limit":5}' --json ``` Exit codes are **0** for success, **1** for a failed call or job, and **2** for a usage, setup, connection or timeout error. Check the exit status before consuming an output file. ### Retries and spending The CLI retries transient failures automatically and keeps the same idempotency key across those retries. To retry an action as a separate command, pass the same `--idempotency-key` and unchanged input. A fresh command without that option gets a fresh key. Paid commands use your normal Ava Studio credits and the key's monthly budget. Failed media jobs can still charge for completed media, and stopping a wait does not cancel production. See [Credits and pricing](/api-and-mcp/credits-and-pricing.md). For `forbidden`, enable the permission the error names. For `insufficient_credits`, top up the account; for `budget_exceeded`, adjust the key's budget in Studio. Errors include a hint and, when available, a request id to share with Ava support. ### Connect an MCP client The CLI can print setup for the hosted MCP server. In Bash, set the key before generating the setup: ```bash read -rs AVA_API_KEY && export AVA_API_KEY avastudio mcp config ``` The default output is a `claude mcp add` command for Claude Code. It references `AVA_API_KEY` rather than printing the key. Run the printed command to register Ava: the shell reads the variable and passes the key to Claude's local configuration. Keep that configuration private. Saving a key with `avastudio login` does not set the environment variable. For other configuration formats: ```bash avastudio mcp config --client cursor avastudio mcp config --client json ``` These JSON formats keep an environment-variable reference in the configuration. Set `AVA_API_KEY` when starting Cursor or Claude Code so the client can fill it in. For Claude.ai or ChatGPT, connect directly with OAuth as described in [Connect your AI app](/api-and-mcp/connect.md). ### API URL, logout and updates The default server is `https://mcp.avastudio.com`. `AVA_API_KEY` and `AVA_API_URL` override saved settings; `--api-url` overrides the saved URL and environment value. ```bash avastudio logout npm install -g @hologramlabs/ava-cli@latest ``` `logout` deletes the saved key. If you set `AVA_API_KEY`, unset it separately. To revoke a key across all clients that use it, use **Settings > Developers** in Ava Studio. ### Next * Browse the [tool reference](/api-and-mcp/tools.md) for all commands' underlying API tools. * Use the [JavaScript and TypeScript SDK](/api-and-mcp/sdk.md) when integrating Ava into application code. * Read [API keys and permissions](/api-and-mcp/api-keys.md) to grant only the access your integration needs.