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

Installation

npm install --save-dev @octavus/cli

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:

# CI/CD or .env.local (not committed)
OCTAVUS_CLI_API_KEY=oct_sk_...  # "Agents" permission only

# Production .env
OCTAVUS_API_KEY=oct_sk_...      # "Sessions" permission only

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:

# Local development (default: .env)
octavus sync ./agents/my-agent

# Staging project
octavus --env .env.staging sync ./agents/my-agent

# Production project
octavus --env .env.production sync ./agents/my-agent

Example environment files:

# .env.staging (syncs to your staging project)
OCTAVUS_CLI_API_KEY=oct_sk_staging_project_key...

# .env.production (syncs to your production project)
OCTAVUS_CLI_API_KEY=oct_sk_production_project_key...

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.

octavus sync ./agents/my-agent

Options:

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

Example output:

ℹ Reading agent from ./agents/my-agent...
ℹ Syncing support-chat...
✓ Created: support-chat
  Agent ID: clxyz123abc456

octavus validate <path>

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

octavus validate ./agents/my-agent

Diagnostics are grouped by severity - errors, warnings, and info recommendations (for example, a tool that will show its name and could use a title). Only errors set a non-zero exit code; warnings and info never fail the command. Pass --json to get the full structured result, including an issues array with each diagnostic's severity, code, and suggestions.

Exit codes:

• 0 - Validation passed (may still include warnings or info)
• 1 - Validation errors
• 2 - Configuration errors (missing API key, etc.)

octavus list

List all agents in your project.

octavus list

Example output:

SLUG                  NAME                            FORMAT        ID
────────────────────────────────────────────────────────────────────────────
support-chat          Support Chat Agent              interactive   clxyz123abc456

1 agent(s)

octavus get <slug>

Get details about a specific agent by its slug.

octavus get support-chat

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.

octavus archive support-chat

Options:

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

Example output:

ℹ Archiving support-chat...
✓ Archived: support-chat
  Agent ID: clxyz123abc456

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.

octavus skills sync ./skills/github

Options:

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

Example output:

ℹ Reading skill from ./skills/github...
ℹ Packaging github...
✓ Created: github
  Skill ID: clxyz789def012
ℹ Pushing 2 secret(s)...
✓ 2 secret(s) updated

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.

my-skill/
├── SKILL.md
├── scripts/
│   └── run.py
└── .env              # Secrets (not included in bundle)

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

Agent Directory Structure

The CLI expects agent definitions in a specific directory structure:

my-agent/
├── settings.json     # Required: Agent metadata
├── protocol.yaml     # Required: Agent protocol
├── prompts/          # Optional: Prompt templates
│   ├── system.md
│   └── user-message.md
└── references/       # Optional: Reference documents
    └── api-guidelines.md

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.

Sharing files across agents

Prompts and references can be symlinks. The CLI follows both file and directory symlinks and syncs the resolved content as ordinary files, so several agents can share one source of truth instead of duplicating it.

For example, an organization with multiple agents that use the same reference documents can keep those documents in one shared directory and symlink them into each agent:

my-org/
├── shared/
│   └── references/
│       ├── brand-voice.md
│       └── api-guidelines.md
├── agent-a/
│   ├── settings.json
│   ├── protocol.yaml
│   └── references/
│       ├── brand-voice.md      -> ../../shared/references/brand-voice.md
│       └── api-guidelines.md   -> ../../shared/references/api-guidelines.md
└── agent-b/
    ├── settings.json
    ├── protocol.yaml
    └── references/
        └── brand-voice.md      -> ../../shared/references/brand-voice.md

Create the links with ln -s (the target is resolved relative to the link's location):

ln -s ../../shared/references/brand-voice.md agent-a/references/brand-voice.md

Editing a file in shared/ updates every agent that links to it on the next octavus sync. The same applies to prompts/ and to skill directories synced with octavus skills sync. A broken symlink (one whose target no longer exists) fails the command with a clear error rather than being silently skipped.

settings.json

{
  "slug": "my-agent",
  "name": "My Agent",
  "description": "A helpful assistant",
  "format": "interactive"
}

protocol.yaml

See the Protocol documentation for details on protocol syntax.

CI/CD Integration

GitHub Actions

name: Validate and Sync Agents

on:
  push:
    branches: [main]
    paths:
      - 'agents/**'

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '22'

      - run: npm install

      - name: Validate agent
        run: npx octavus validate ./agents/support-chat
        env:
          OCTAVUS_CLI_API_KEY: ${{ secrets.OCTAVUS_CLI_API_KEY }}

      - name: Sync agent
        run: npx octavus sync ./agents/support-chat
        env:
          OCTAVUS_CLI_API_KEY: ${{ secrets.OCTAVUS_CLI_API_KEY }}

Package.json Scripts

Add sync scripts to your package.json:

{
  "scripts": {
    "agents:validate": "octavus validate ./agents/my-agent",
    "agents:sync": "octavus sync ./agents/my-agent"
  },
  "devDependencies": {
    "@octavus/cli": "^0.1.0"
  }
}

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

# After syncing: octavus sync ./agents/support-chat
# Output: Agent ID: clxyz123abc456

# Add to your .env file
OCTAVUS_SUPPORT_AGENT_ID=clxyz123abc456

const agentId = process.env.OCTAVUS_SUPPORT_AGENT_ID;

const sessionId = await client.agentSessions.create(agentId, {
  COMPANY_NAME: 'Acme Corp',
});