CLI

Octopus CLI

Review PRs, index repos, and chat with your codebase — all from the terminal.

Installation

npm install -g @octp/cli

Or with bun:

bun add -g @octp/cli

Authentication

octopus login

You can also authenticate with an API token directly:

octopus login --token oct_your_token_here

Verify your session with whoami:

octopus whoami

Repository Commands

Manage your repositories. When run inside a git repo, the [repo] argument is auto-detected from the git remote.

octopus repo list

List all repositories in your organization.

octopus repo status [repo]

Show detailed status — indexing progress, analysis results, PR count.

octopus repo index [repo]

Index a repository for code search and review context. Polls until complete.

octopus repo analyze [repo]

Run AI analysis to generate a codebase summary and architecture overview.

octopus repo chat [repo]

Start an interactive chat session about your codebase. Ask questions, explore architecture.

Pull Request Commands

octopus pr review <pr>

Trigger an AI review on a pull request. Accepts a PR number or full URL.

Examples:

octopus pr review 42
octopus pr review https://github.com/owner/repo/pull/42

Dependency Analysis

Analyze npm dependencies in a GitHub repository for security risks. Results stream in real-time with risk categorization.

octopus analyze-deps <repo-url>

Scan a repository's npm dependencies for known vulnerabilities, malicious packages, and supply chain risks.

Example:

octopus analyze-deps https://github.com/acme/backend

Knowledge Base

Add custom documents to your organization's knowledge base. Octopus uses these during reviews for deeper context.

octopus knowledge list

List all knowledge documents.

octopus knowledge add <file> [--title "Title"]

Upload a file to the knowledge base.

octopus knowledge remove <id>

Remove a knowledge document.

Local Agent

Run a local agent on your machine to supercharge Octopus Chat with real-time code search. When someone asks a question in chat, the agent searches your actual source code (via ripgrep or Claude CLI) and returns precise results — much more accurate than embeddings alone.

octopus agent watch [path]

Add a directory to the agent's watch list. Detects the repository from the git remote URL.

# Watch current directory
octopus agent watch

# Watch a specific path
octopus agent watch ~/Repos/api

# List all watched directories
octopus agent watch --list

# Remove a directory from the watch list
octopus agent watch --remove

octopus agent start

Start the local agent daemon. Registers with Octopus and listens for search requests from chat.

# Start with ripgrep (fast, default)
octopus agent start

# Enable Claude CLI for deep semantic search
octopus agent start --with-claude

# Verbose mode for debugging
octopus agent start --verbose

The agent identifies repositories by their git remote URL, not the folder name — so you can clone a repo to any directory and the agent will still match it correctly. When chat receives a question, the server dispatches a search request to any online agent that has the relevant repo. Results are merged with RAG context for more accurate answers.

Ripgrep mode: Fast keyword search, 8s timeout, no extra dependencies

Claude CLI mode: Semantic search with --with-claude, 30s timeout, requires Claude CLI

Skills

Install and manage Octopus skills for AI coding agents like Claude Code and Codex. Skills are reusable automation workflows that run inside your AI editor. See the Skills docs for details on each skill.

octopus skills list

List available Octopus skills.

$ octopus skills list

  Skill        Description
  octopus-fix  Check open PRs for review comments, apply fixes, and push updates

octopus skills install

Install Octopus skills for AI coding agents. By default installs for both Claude Code and Codex.

# Install for both Claude Code and Codex
octopus skills install

# Install only for Claude Code
octopus skills install --claude

# Install only for Codex
octopus skills install --codex

Once installed, you can use the skills as slash commands:

Claude Code: /octopus-fix

Codex: Automatically available as a skill

Configuration & Usage

octopus config list

List all CLI profiles.

octopus config set <key> <value>

Set a config value (apiUrl, activeProfile).

octopus usage

Show monthly token usage, spend limits, and credit balance.

octopus logout

Remove saved credentials.

Multiple Profiles

Use profiles to switch between different accounts or organizations:

octopus login --profile work
octopus login --profile personal
octopus config set activeProfile work

.octopusignore

Control which files Octopus reviews and indexes by creating a .octopusignore file at the root of your repository. It uses the same syntax as .gitignore.

# Generated files
docs/generated/**

# Test fixtures
tests/fixtures/**
**/__snapshots__/**

# Vendor / third-party
vendor/**
third-party/**

# Large data files
*.csv
*.parquet

Matched files are excluded from both indexing (never chunked or embedded) and PR review (the AI reviewer won't see changes to those files).

See the full .octopusignore reference for syntax details, common patterns, and provider support.