Octavus CLI

The @octavus/cli package provides a command-line interface for validating and syncing agent definitions from your local filesystem to the Octavus platform.

Current version: 2.19.0

Installation

Configuration

The CLI requires an API key with the Agents permission.

Environment Variables

Two-Key Strategy (Recommended)

For production deployments, use separate API keys with minimal permissions:

This ensures production servers only have session permissions (smaller blast radius if leaked), while agent management is restricted to development/CI environments.

Multiple Environments

Use separate Octavus projects for staging and production, each with their own API keys. The --env flag lets you load different environment files:

Example environment files:

Each project has its own agents, so you'll get different agent IDs per environment.

Global Options

Commands

octavus sync <path>

Sync an agent definition to the platform. Creates the agent if it doesn't exist, or updates it if it does.

Options:

• --json — Output as JSON (for CI/CD parsing)
• --quiet — Suppress non-essential output

Example output:

octavus validate <path>

Validate an agent definition without saving. Useful for CI/CD pipelines.

Exit codes:

• 0 — Validation passed
• 1 — Validation errors
• 2 — Configuration errors (missing API key, etc.)

octavus list

List all agents in your project.

Example output:

octavus get <slug>

Get details about a specific agent by its slug.

octavus archive <slug>

Archive an agent by slug (soft delete). Archived agents are removed from the active agent list and their slug is freed for reuse.

Options:

• --json — Output as JSON (for CI/CD parsing)
• --quiet — Suppress non-essential output

Example output:

octavus skills sync <path>

Sync a skill to the platform. Packages the skill directory into a bundle (excluding .env files, .git, and node_modules), uploads it, and optionally pushes secrets from the skill's .env file.

Options:

• --json — Output as JSON (for CI/CD parsing)
• --quiet — Suppress non-essential output

Example output:

Secret handling:

If the skill directory contains a .env file, secrets are pushed alongside the bundle. Secrets are cross-validated against the secrets declarations in SKILL.md — warnings are shown for undeclared or missing required secrets.

See Skills for details on skill format, secrets, and secure mode.

Agent Directory Structure

The CLI expects agent definitions in a specific directory structure:

references/

Reference files are markdown documents with YAML frontmatter containing a description. The agent can fetch these on demand during execution. See References for details.

settings.json

protocol.yaml

See the Protocol documentation for details on protocol syntax.

CI/CD Integration

GitHub Actions

Package.json Scripts

Add sync scripts to your package.json:

Workflow

The recommended workflow for managing agents:

1. Define agent locally — Create settings.json, protocol.yaml, and prompts
2. Validate — Run octavus validate ./my-agent to check for errors
3. Sync — Run octavus sync ./my-agent to push to platform
4. Store agent ID — Save the output ID in an environment variable
5. Use in app — Read the ID from env and pass to client.agentSessions.create()