Zenith Studio CLI

@zenith-studio/cli connects your terminal and coding agent to Zenith Studio, a platform for creating and managing media. Use it to generate images, video, voice, audio, and music; organize projects, jobs, and assets; download results; and install the official Zenith Studio workflows for Codex or Claude Code.

The CLI keeps the agent workflow on your machine. Zenith Studio handles only the remote media jobs you ask it to run.

The npm package is @zenith-studio/cli; the terminal command is zenith-studio.

Install

Requires Node.js 22 or newer.

npm install --global @zenith-studio/cli
zenith-studio setup

setup signs you in, detects Codex and Claude Code, and lets you choose where to install the bundled workflows. If setup was already offered during the npm install, you do not need to run it again.

Quick start

List the media models available to your account:

zenith-studio models list

Create a project:

zenith-studio projects create --title "My first project"

The command returns a project ID and a local workspace path. Use the project ID to submit a job:

zenith-studio generate image \
  --project PROJECT_ID \
  --model MODEL_ID \
  --label "Sunrise Cabin" \
  --prompt "A quiet cabin beside a lake at sunrise"

Then wait for the job and download its result:

zenith-studio jobs wait PROJECT_ID NODE_ID
zenith-studio assets download PROJECT_ID NODE_ID

By default, downloaded files are saved in the project's workspace under ~/.zenith-studio-cli/.

Generate media

Zenith Studio supports image, video, voice, audio, and music commands:

zenith-studio generate image --project PROJECT_ID --model MODEL_ID --label "Product Hero" --prompt "..."
zenith-studio generate video --project PROJECT_ID --model MODEL_ID --label "Opening Reveal" --prompt "..."
zenith-studio generate voice --project PROJECT_ID --model MODEL_ID --label "Main Narration" --text "..."
zenith-studio generate audio --project PROJECT_ID --model MODEL_ID --label "Rain Ambience" --prompt "..."
zenith-studio generate music --project PROJECT_ID --model MODEL_ID --label "Warm Theme" --prompt "..."

Use a meaningful 1–3 word label for every node. Longer or generic labels such as CLI Image are rejected. When omitted for compatibility, the CLI derives a short label from the prompt.

Check the model catalog before generating. It shows which models your account can use and which media type each model accepts:

zenith-studio models list --kind video

Use --param key=value for model-specific settings. Run zenith-studio generate image --help to see reference-image, frame, and other input options.

Projects, jobs, and assets

# Projects
zenith-studio projects list
zenith-studio projects resolve PROJECT_ID

# Jobs
zenith-studio jobs get PROJECT_ID NODE_ID
zenith-studio jobs wait PROJECT_ID NODE_ID --timeout 1800
zenith-studio jobs cancel PROJECT_ID NODE_ID

# Assets
zenith-studio assets upload PROJECT_ID ./product.png
zenith-studio assets download PROJECT_ID NODE_ID --output ./result.png

jobs wait only watches a job. Pressing Ctrl-C or reaching the local timeout does not cancel the Zenith Studio job.

For agents, use --json jobs wait PROJECT_ID NODE_ID. A failed generation exits with code 6. jobs get is a status query: it exits successfully even for a failed job; inspect data.status and data.error.

API failures return {ok:false,error:<original response body>,http_status:...}. Failed jobs return {ok:false,error:<original node error>,project_id:...,node_id:...} with execution ID and node data alongside the error. Human stderr prints the same raw error. No error classification, rewritten advice, redaction, or truncation is applied. Old backend error objects, strings, arrays, and null errors are passed through unchanged.

Use with Codex or Claude Code

zenith-studio setup is the easiest way to install the integrations. You can also install one explicitly:

zenith-studio integrations install codex
zenith-studio integrations install claude-code

The integration includes:

• $zenith-studio-cli, the single entry point for creating and managing images, video, voice, audio, and music with Zenith Studio. Video requests automatically use the built-in end-to-end workflow; no separate video skill is required
• $zenith-studio-cli-skill-installer for installing custom skills you saved in Zenith Studio

Restart your coding-agent session after installation. Run the same command again whenever you want to update the workflows.

Installation replaces the managed skills and removes the former ii-factory and ii-factory-skill-installer integrations so they do not compete with Zenith Studio. Unrelated skills are preserved.

Export for Zenith Team

Available since 0.1.8. Zenith Team can install the normal npm package automatically with ZENITH_STUDIO_CLI_SKIP_SETUP=1, then export the complete host-specific Skill without accessing an account or installing provider-wide skills:

zenith-studio --json integrations export boardly --output ./boardly-studio-export

The adapter source lives in skills/adapters/zenith-team/. The export command and exported manifest retain boardly for compatibility with Zenith Team.

The Team adapter translates shared video workflows into public CLI media generation and local HyperFrames composition on the Run's computer. Its export requires both references/media-generation.md and references/assembly.md. The Agent checks the local renderer before paid generation for an assembled video, reuses successful clips, and delivers the reviewed local render through present_output. Studio Connect/Repair does not install HyperFrames. A source canvas records the real Studio inputs; a local render does not acquire a fabricated remote Final Output node.

The output directory must not exist, its parent must already exist, and it must be outside the package's skills tree. Existing files, directories and symlink destinations are refused. The export is assembled in a temporary sibling and published only after composition and validation succeed. Choose a new output directory for each export.

boardly-studio-export/
  manifest.json
  skills/
    zenith-studio-cli/
      SKILL.md
      references/...
      resources/...

JSON stdout is one {ok:true,data:{outputDirectory,manifestPath,manifest}} result. manifest is also written verbatim as formatted JSON in manifest.json. The v1 manifest uses camelCase fields:

| Field | Meaning | | --- | --- | | schemaVersion / host | 1 / "boardly" | | package.name / package.version | Source npm package and its installed version | | skills[].key / name | Stable Skill key; both are "zenith-studio-cli" for this release | | skills[].description | The adapter's plain, single-line frontmatter description | | skills[].directory / entrypoint | Export-relative directory and "SKILL.md" inside it | | skills[].contentHash | Lowercase SHA-256 of the canonical content stream below | | skills[].sizeBytes / fileCount | Total file bytes and number of files, including SKILL.md | | skills[].files[] | {path,hash,size,text}: Skill-relative POSIX path, lowercase SHA-256, byte length and UTF-8 classification |

Files and Skills are sorted lexicographically by their UTF-8 path/key bytes. For each sorted file, append its path's UTF-8 byte length as an unsigned 64-bit big-endian integer, the path bytes, its content length as an unsigned 64-bit big-endian integer, then the unmodified content bytes. contentHash is SHA-256 of that concatenated stream, matching Zenith Team's Skill content identity. Per-file hash is SHA-256 of just the file bytes. The manifest contains no timestamps or absolute paths, so exporting the same package version/content to another directory produces identical manifest bytes.

The export includes the canonical workflow and the Zenith Team adapter. It checks required files, forbids symlinks and unsupported paths, and enforces the Zenith Team file/size limits. The export manifest is a release artifact, not a Run index: Zenith Team owns assignment, content verification, the Run identity envelope and provider/MCP delivery. Export itself does not enable a Department or grant tools.

The Zenith Team adapter uses skillKey for reference reads, ask_human for required founder input, and present_output for final workspace files. CLI setup and interactive authentication belong outside the Agent Run. Existing auth login and auth status commands remain available; no media or authentication API changes are required. Delivered media appears in the native output card; the Agent replies with a short summary instead of duplicate file links.

Download your Zenith Studio skills

Download the private custom skills you have saved in your Zenith Studio account:

zenith-studio skills list
zenith-studio skills download SKILL_ID

The list only includes skills owned by the signed-in account. Download saves the selected skill as a ZIP; it does not install it. To use the skill in Codex or Claude Code, ask your agent to run $zenith-studio-cli-skill-installer.

Authentication

zenith-studio auth login
zenith-studio auth status
zenith-studio auth logout

Login normally opens your browser. For SSH, containers, or a browser on another machine, use:

zenith-studio auth login --manual-code

Credentials are stored locally under ~/.zenith-studio-cli/ and are never printed by the CLI. Logging out removes the local session but keeps downloaded assets.

The rename does not copy the former ~/.ii-factory/ or ~/.factory/ directories automatically. Sign in again for the safest migration. If you deliberately reuse the old directory for a transition, set ZENITH_STUDIO_CLI_HOME to it. Stored credentials retain their original client ID for refresh and revocation; legacy credentials without a client ID use factory-cli. Reusing the old directory does not migrate project manifests or custom-skill provenance: resolve projects again with zenith-studio projects resolve PROJECT_ID and reinstall custom skills in the new workspace. Existing downloads remain in their original directories. Do not run the old and new CLIs concurrently against the same credential store.

New sign-ins use the OAuth client ID zenith-studio-cli; the backend must allow this client ID. The production API origin is unchanged.

Configuration

Use ZENITH_STUDIO_CLI_API_URL to select a backend and ZENITH_STUDIO_CLI_HOME to change the local data directory. The former II_FACTORY_API_URL and II_FACTORY_HOME variables are no longer read.

export ZENITH_STUDIO_CLI_API_URL="https://api-agent.ii.inc"
zenith-studio models list

--api-url takes precedence over the environment variable, followed by the stored credential's API origin and then the production default. Set ZENITH_STUDIO_CLI_SKIP_SETUP=1 to skip setup during a global npm install.

Backend protocol identifiers such as /v1/factory/..., OAuth scopes, and factory_* web tools retain their existing names for compatibility. They refer to Zenith Studio; they are not alternative CLI commands or product names. The web skill/resource IDs factory-video and factory-commons, shared factory-*.md resource paths, and assets/factory-assets.json ledger also stay unchanged. Internal Factory* types and stable factory_* JSON error codes are implementation and compatibility identifiers.

JSON output

Add --json to any command when calling the CLI from a script or agent:

zenith-studio --json auth status
zenith-studio --json models list

Stdout contains one JSON document, while progress and diagnostics go to stderr. Check ok before reading data; errors include a stable category and code.

Development

The test suite also requires python3 to exercise the bundled custom-skill installer.

npm install
npm run typecheck
npm test
npm run build
npm run pack:check

Run zenith-studio --help or zenith-studio <command> --help for the complete command reference.

Export a source canvas

Read the saved positions, prompts, models and recorded source dependencies of CLI-generated media without generating anything:

zenith-studio canvas export PROJECT_ID \
  --node OUTPUT_NODE_ID --output-item OUTPUT_NODE_ID:0 \
  --output source.canvas.json

Repeat --node for multiple output nodes. --output-item NODE_ID:ORDINAL maps each downloaded media file to its zero-based index in Zenith Team's output items. The output file is plain JSON (not the CLI envelope); existing files are never replaced. In a Team Run, pass studioCanvasPath: "source.canvas.json" to present_output alongside the media items. Existing Team results support importing this file from their Canvas tab.

Exports follow recorded CLI generation node/asset references, preserve positions, and contain no credentials or temporary media URLs. URL-only references have no canvas node. Native Studio nodes with unreadable source lineage and ambiguous asset-to-node mappings fail explicitly rather than producing an incomplete graph. The export is a snapshot at read time, not a reconstruction of an older node version.