Octavus Docs

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: 0.2.0

Installation

bash

Configuration

The CLI requires an API key with agent management permissions.

Environment Variables

VariableDescription
OCTAVUS_CLI_API_KEYAPI key with agent management permissions (recommended)
OCTAVUS_API_KEYFallback if OCTAVUS_CLI_API_KEY not set
OCTAVUS_API_URLOptional, defaults to https://octavus.ai

For production deployments, use separate API keys:

bash

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:

bash

Example environment files:

bash

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

Global Options

OptionDescription
--env <file>Load environment from a specific file (default: .env)
--helpShow help
--versionShow version

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.

bash

Options:

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

Example output:

text

octavus validate <path>

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

bash

Exit codes:

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

octavus list

List all agents in your project.

bash

Example output:

text

octavus get <slug>

Get details about a specific agent by its slug.

bash

Agent Directory Structure

The CLI expects agent definitions in a specific directory structure:

text

settings.json

json

protocol.yaml

See the Protocol documentation for details on protocol syntax.

CI/CD Integration

GitHub Actions

yaml

Package.json Scripts

Add sync scripts to your package.json:

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()
bash
typescript