Onklave Agent CLI

The official command-line interface for the Onklave platform. Run AI agent tasks locally with cloud orchestration, policy enforcement, and audit trails.

@onklave/agent-cli is the bridge between your terminal and the Onklave platform: it authenticates your machine, ships agent tasks to a centrally-managed execution surface, streams progress back, and enforces the same guardrails, approvals, and audit logs that the Onklave portal applies to every other agent invocation.

Why use it

• Local feel, cloud governance. Agents run against your working tree, but every invocation is tracked centrally — start/stop times, model used, persona, approvals, output. No more untracked Claude/Cursor runs hidden in shells.
• Policy enforcement before, not after. Per-project .onklave.json declares which tools and paths agents may touch and which commands require human approval. Violations fail the task instead of escaping into a commit.
• Multi-machine fleet awareness. Register every machine that runs agents (laptop, CI runner, server). The portal shows what's active where, and who claimed which task.
• Same Claude models, same APIs. This CLI doesn't replace your model provider — it routes through it. Bring your own Anthropic API key or use platform-managed credentials.

Installation

npm install -g @onklave/agent-cli

Requires Node.js >= 18. Verify the install:

onklave --version

Quick start

# 1. Authenticate this machine
onklave login --token <your-cli-token>

# 2. Confirm identity
onklave whoami

# 3. Run a diagnostic to catch missing tools / wrong Node version / unreachable platform
onklave doctor

# 4. Initialise a project (writes .onklave.json with sensible defaults)
cd my-project
onklave init

# 5. Run an agent task
onklave run --task "Add unit tests for the auth module"

Get a CLI token by signing in to the Onklave portal → Settings → API Tokens → Generate new token. Pick an expiry (Never / 30 days / 90 days / 1 year) and a descriptive name (e.g. laptop-cli). The plaintext is shown once — copy it immediately; it can't be retrieved later. Revoke any token from the same page.

Commands

| Command | Purpose | | ----------------------------- | ------------------------------------------------------ | | onklave login | Authenticate this machine against the platform | | onklave logout | Remove stored credentials | | onklave whoami | Show current identity, org, and auth status | | onklave doctor | Run diagnostic checks (Node version, auth, network) | | onklave init | Create .onklave.json in the current directory | | onklave config | View or modify configuration (get/set/effective) | | onklave register | Register this machine as an agent runner | | onklave run | Start an agent task | | onklave status [session-id] | Show one session, or list all active sessions | | onklave logs <session-id> | Stream / fetch logs for a session | | onklave stop <session-id> | Stop a running session | | onklave approve <session-id>| Approve a pending approval gate | | onklave deny <session-id> | Deny a pending approval gate |

Run any command with --help for its full flag list.

onklave run — the primary verb

onklave run --task "Refactor the order service to extract the payment adapter"

Common flags

| Flag | Default | Description | | -------------------------- | ------------- | ---------------------------------------------- | | --task <text> | (required) | One-line task description | | --context <path> | . | Working directory the agent operates in | | --persona <name> | from config | Persona profile (e.g. security-reviewer) | | --workflow <name> | from config | Named workflow defined in the portal | | --model <model> | from config | Override the model (e.g. claude-opus-4-7) | | --timeout <seconds> | 120 | Hard cap on session runtime | | --tui | auto on TTY | Interactive terminal UI | | --headless | (off) | No interactive UI; ideal for CI | | --api-endpoint <url> | platform URL | Override platform API endpoint | | --dry-run | (off) | Print resolved config and exit without running |

Examples

# Interactive run with the default persona/model
onklave run --task "Investigate the flaky e2e test in checkout.spec.ts"

# Bound persona + a specific model
onklave run \
  --task "Audit the JWT verification code path" \
  --persona security-reviewer \
  --model claude-opus-4-7

# Non-interactive (CI-friendly)
onklave run --task "Generate the release notes for v2.4.0" --headless

# Validate config without spending any tokens
onklave run --task "Refactor auth" --dry-run

While a task is running, the portal shows live status and any approval gates triggered by your guardrails. Approve or deny them from the CLI:

onklave approve abc123
onklave deny    abc123

Configuration

Configuration resolves in this order (highest priority first):

1. Command-line flags — --model, --persona, --timeout, etc.
2. Environment variables — ONKLAVE_*, ANTHROPIC_API_KEY.
3. Project config — .onklave.json in the current directory.
4. Global config — ~/.config/onklave/config.json.
5. Platform defaults — set per-org in the portal.

Use onklave config to inspect or change values:

onklave config                       # show effective configuration with sources
onklave config get defaultModel
onklave config set defaultModel claude-sonnet-4-6

.onklave.json (project-scoped)

onklave init writes this template. Edit to suit your project:

{
  "project": "my-service",
  "org": "your-onklave-org-id",
  "defaults": {
    "persona": "",
    "workflow": "",
    "model": "claude-sonnet-4-20250514",
    "timeout": 120
  },
  "guardrails": [
    {
      "name": "no-secrets-access",
      "match": "file_*",
      "action": "deny",
      "reason": "Prevent access to secret files",
      "paths": [".env*", "*.pem", "*.key"]
    },
    {
      "name": "approve-destructive-commands",
      "match": "cmd:rm*",
      "action": "require_approval",
      "reason": "Destructive commands require approval"
    }
  ],
  "permissions": {
    "tools_allowed": [],
    "tools_denied": [],
    "paths_readable": ["."],
    "paths_writable": ["src/", "tests/", "docs/"]
  },
  "context": {
    "includes": ["src/", "package.json", "tsconfig.json"],
    "system_prompt_append": ""
  }
}

• guardrails are evaluated for every tool the agent attempts. Actions: deny, require_approval, allow.
• permissions.paths_writable is enforced before the agent edit reaches your filesystem — anything outside this list fails fast.
• context.system_prompt_append lets you append project conventions to every run without retyping them.

Authentication

onklave login --token <your-cli-token> [--platform-url <url>]

Tokens are stored at ~/.config/onklave/credentials.json (mode 0600). Remove with onklave logout.

To register the machine itself (so it shows up in Settings → Machines as an agent runner that can claim work):

onklave register --token <linking-token>

The linking token is generated in the portal under Settings → Machines → Register Machine.

Revoking access

Tokens can be revoked instantly from the portal — Settings → API Tokens → ⋯ → Revoke. Revocation takes effect within ~5 minutes (cached resolves expire on that interval).

If you suspect a token has been leaked, revoke it immediately. Existing CLI sessions that have already authenticated continue to work for the user but lose access on their next API call.

Diagnostics

If something looks off:

onklave doctor

Checks node version, auth state, platform reachability, working-directory permissions, and the local config files. Each failure prints an actionable fix line.

CI usage

# Example GitHub Actions step
- name: Run release notes agent
  run: |
    npm install -g @onklave/agent-cli
    onklave login --token "${{ secrets.ONKLAVE_CLI_TOKEN }}"
    onklave run \
      --task "Draft release notes for ${{ github.ref_name }}" \
      --headless \
      --timeout 600

Use --headless so there's no TTY-only spinner / interactive UI, and pin the timeout to your job budget.

Where things live

| Path | Purpose | | ---------------------------------------------- | -------------------------------------- | | ~/.config/onklave/credentials.json | API token, device token, refresh state | | ~/.config/onklave/config.json | Global per-user config | | ./.onklave.json | Project-scoped config (commit this) |

credentials.json is created 0600. Never commit it.

Telemetry

The CLI sends task metadata (id, persona, model, duration, outcome) to your Onklave org for the same reasons every other request to the platform does: audit trail, billing, fleet visibility. No source code is uploaded unless the agent's tool explicitly reads and includes it, and even then it's bound by your .onklave.json permissions.

Links

• Onklave portal: https://portal.onklave.app
• Documentation: https://docs.onklave.app/cli
• Issues / feedback: https://github.com/onklave/onklave-platform/issues

License

Apache-2.0 — see LICENSE.