Octopus/Docs/CLI
Get Started
CLI

Octopus CLI

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

Installation

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

Or on Windows (PowerShell):

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

Let your AI handle setup

Give the homepage setup prompt to the AI working in your project. With octp 0.5.0 or later, it can connect your GitHub repository, start or join indexing and analysis, and check the result through the CLI.

Code
octp onboard --agent --json

Run this from the project directory, or supply --repo owner/name. Use --account name to select a saved user profile, and --org slug to choose an organisation for one command.

If sign-in is needed, the AI runs the returned login command with --no-open, gives you the approval URL, and keeps that process running while you approve. GitHub App installation and repository access also return approval links. Approve those in your browser, then let the AI continue through the CLI.

Agent setup currently supports github.com repositories. Existing organisation settings stay in place; dismissed repositories and failed jobs need explicit attention. If login is interrupted, start it again. See the agent protocol reference for JSON fields, continuation arguments, exit codes and recovery limits.

Authentication

Log in to connect the CLI with your Octopus account. This opens a browser window for authentication.

Code
octp login

CLI 0.6.0 with server 1.0.157 signs you in once without selecting an organisation in the browser. Your session lasts 30 days. Run octp logout to revoke it.

Code
octp org list --json
octp --org acme onboard --agent --json --repo acme/app
octp --org another-org repo list

Without --org, repository setup uses a unique repository or GitHub owner match. If it cannot choose safely, it returns organization_required with your available organisations before starting work. Choose one and retry. Existing organisation tokens keep their original scope; run octp login again to enable switching.

You can also authenticate with an API token directly:

Code
octp login --token oct_your_token_here

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

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

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

Review Local Changes

Run these from your Git repository. The first command can include commits since the upstream branch and unstaged tracked changes, but may omit staged-only changes. Inspect the intended diff first; use the second command for staged changes. Untracked files are not included.

Code
octp review --no-index --format json
octp review --staged --no-index --format json

Reviews send the selected diff to your configured Octopus server and use your organisation's review budget. --no-index skips new working-tree indexing; existing repository context can still be used. If the output reports truncated: true, split the changes before treating the review as complete.

Pull Request Commands

octp review --pr <pr>

Trigger an AI review on a pull request. Accepts a PR number or full GitHub, GitLab, or Bitbucket PR URL.

Examples:

Code
octp review --pr 42
octp review --pr https://github.com/owner/repo/pull/42

For Forgejo, run the command from the connected repository checkout and use its PR number; native CLI 0.6.0 does not accept Forgejo PR URLs. This queues a review that posts comments on the pull request. A successful command confirms the request was accepted. Follow completion in Review Logs and on the pull request.

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:

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

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

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

Use a distinct organization API token for each agent that needs an independent security boundary. Agents configured with the same token intentionally share task and repository authority.

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

Use with Your AI Agent

Claude Code, Codex, OpenCode, Hermes, OpenClaw, and Cursor can use the native Octopus CLI through their shell tools. Follow the setup guide for your agent, including an optional Octopus skill and a connection check.

Set up your AI agent →

Skills

The octp skills commands install the existing Claude Code command library into .claude/commands in your current project. Sign in first, then run them from the project root. See the Skills docs for details on each skill.

octp skills list

List available Octopus skills.

Code
$ octp skills list

  Skill        Description
  octopus-fix  Check open PRs for review comments, apply fixes, and push updates
octp skills install <name>

Install a named command into this project's .claude/commands directory.

Code
# Install one command
octp skills install octopus-fix

# Install the whole command library
octp skills install --all

Use /octopus-fix in Claude Code after installation. For Codex and other agents, use the separate AI agent setup guide.

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 for different users or servers. Within one user account, switch organisations with --org:

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

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