CLI

Octopus CLI

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

Installation

curl -fsSL https://octopus-review.ai/install.sh | bash

Or on Windows (PowerShell):

powershell -c "irm https://octopus-review.ai/install.ps1 | iex"

Authentication

octp login

You can also authenticate with an API token directly:

octp login --token oct_your_token_here

Need a token for CI/CD or a script? Use setup-token. It runs the same browser approval flow but prints the token to stdout (progress messages go to stderr) so it can be captured directly:

# Print token to stdout
octp setup-token

# Capture into an environment variable
export OCTOPUS_TOKEN=$(octp setup-token)

# Save into a local profile while also printing
octp setup-token --save --profile ci

# Headless box (no browser): URL is written to stderr so you can open it elsewhere
octp setup-token --no-open

Prefer a manually-managed, named token? Create one at Settings → API Tokens and pass it with octp login --token oct_....

Verify your session with whoami:

octp whoami

Repository Commands

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

octp repo list

List all repositories in your organization.

octp repo status [repo]

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

octp repo index [repo]

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

octp repo analyze [repo]

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

octp chat [repo]

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

Pull Request Commands

octp review --pr <pr>

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

Examples:

octp review --pr 42
octp review --pr 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.

octp analyze-deps <repo-url>

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

Example:

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

octp knowledge list

List all knowledge documents.

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

Upload a file to the knowledge base.

octp 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, with a pure-Node fallback) and returns precise results — much more accurate than embeddings alone.

octp agent watch [path]

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

# Watch current directory
octp agent watch

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

# List all watched directories
octp agent watch --list

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

octp agent serve

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

# Start the agent (ripgrep-backed code search)
octp agent serve

# Verbose mode for debugging
octp agent serve --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.

Code search: ripgrep-backed keyword search, with a pure-Node file-walker fallback when ripgrep isn't installed

LLM tasks: optional, served by a local Ollama instance — no cloud calls

Claude Code Integration

Use Octopus directly inside Claude Code with the official plugin. Review PRs, auto-fix findings, and chat with your codebase without leaving the terminal.

View Claude Code Integration docs →

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.

octp skills list

List available Octopus skills.

$ octp skills list

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

octp 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
octp skills install

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

# Install only for Codex
octp 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

octp config list

List all CLI profiles.

octp config set <key> <value>

Set a config value (apiUrl, activeProfile).

octp usage

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

octp logout

Remove saved credentials.

Multiple Profiles

Use profiles to switch between different accounts or organizations:

octp login --profile work
octp login --profile personal
octp 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.