Skip to main content
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: 6.4.0

Installation

bash
npm install --save-dev @octavus/cli

Configuration

The CLI requires an API key with the Agents permission.

Environment Variables

VariableDescription
OCTAVUS_CLI_API_KEYAPI key with "Agents" permission (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 with minimal permissions:

bash
# 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:

bash
# 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:

bash
# .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

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
octavus sync ./agents/my-agent

Options:

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

Example output:

text
ℹ 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.

bash
octavus validate ./agents/my-agent

Exit codes:

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

octavus list

List all agents in your project.

bash
octavus list

Example output:

text
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.

bash
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.

bash
octavus archive support-chat

Options:

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

Example output:

text
ℹ 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.

bash
octavus skills sync ./skills/github

Options:

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

Example output:

text
ℹ 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.

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

text
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.

settings.json

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

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

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()
bash
# After syncing: octavus sync ./agents/support-chat
# Output: Agent ID: clxyz123abc456

# Add to your .env file
OCTAVUS_SUPPORT_AGENT_ID=clxyz123abc456
typescript
const agentId = process.env.OCTAVUS_SUPPORT_AGENT_ID;

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