Octopoda CLI commands and flags

Reference for every octopoda command: login, scan, status, findings, fix, mcp, whoami, logout, update and version, with their flags and output.

This page lists every octopoda command and flag. Run octopoda help to print the same summary in your terminal. Commands other than login, update and version need you to be signed in, or OCTOPODA_TOKEN to be set.

​

octopoda login

Signs this device in to your Octopoda account.

octopoda login [--no-browser]

The CLI prints a code and opens a link in your browser. Check that the code matches, then approve. Over SSH the browser is not opened.

Flag	Description
--no-browser	Print the link instead of opening a browser. Open it on any device.

Each signed-in device appears in Settings → CLI sessions in the web app, where you can sign it out.

​

octopoda scan

Packs a project folder, uploads it and starts a code scan, then follows it until it ends.

octopoda scan [path] [flags]

path defaults to the current folder. Flags can come before or after it. A code scan uses 5 credits. See Choose what gets scanned for what is uploaded.

Flag	Description
--instructions <text>	Extra guidance for this scan, such as what changed or what to focus on.
--no-wait	Start the scan and return right away with its number and link.
--json	Print the result as JSON: the scan, its findings and its link.
--fail-on <level>	Exit with code 1 if a finding at or above critical, high, medium or low is proven.

While it follows the scan, the CLI prints each stage and each finding as it is proven. Press Ctrl+C to stop following; the scan keeps running. When the scan ends, the CLI lists the findings, most severe first, and suggests the octopoda fix command for the first one.

The command exits with code 1 if the scan failed, or if --fail-on matched a finding. See exit codes.

​

octopoda status

Shows a scan: its stage and the findings so far while it runs, or its result once it has ended.

octopoda status [scan]

Without scan, shows your latest scan. Pass a scan ID, which starts with scn_ and appears in the scan’s link, to show another.

​

octopoda findings

Lists the open findings in your account, grouped by repository or upload, with each finding’s key, severity, title and location.

octopoda findings [--severity <level>] [--json]

Flag	Description
--severity <level>	Only findings of this severity: critical, high, medium or low.
--json	Print the findings as JSON.

​

octopoda fix

Prints a finding’s fix prompt, ready to paste into Cursor or Claude Code.

octopoda fix <finding>

finding is a key such as F-142 (the F- is optional) or a finding ID. In a terminal, the CLI prints the severity, title and what is wrong before the prompt. When the output is piped, it prints only the prompt:

octopoda fix F-142 | pbcopy

See Fix a finding with your AI tool.

​

octopoda mcp

Runs the Octopoda MCP server over standard input and output, for AI coding tools. You don’t run it yourself: your AI tool starts it. See MCP server.

​

octopoda whoami

Shows who the CLI is signed in as: your GitHub username, the account, your role and its plan.

octopoda whoami

​

octopoda logout

Signs this device out on Octopoda and deletes the saved sign-in.

octopoda logout

​

octopoda update

Installs the latest version of the CLI after checking its checksum and signature. See Install and update the CLI.

​

octopoda version

Prints the installed version. octopoda --version and octopoda -v do the same.