> ## Documentation Index
> Fetch the complete documentation index at: https://docs.octopoda.dev/llms.txt
> Use this file to discover all available pages before exploring further.

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

```bash theme={null}
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.

```bash theme={null}
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](https://docs.octopoda.dev/scanning/excluding-files.md) 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](https://docs.octopoda.dev/integrations/ci.md#exit-codes).

## `octopoda status`

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

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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:

```bash theme={null}
octopoda fix F-142 | pbcopy
```

See [Fix a finding with your AI tool](https://docs.octopoda.dev/findings/fix-with-ai.md).

## `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](https://docs.octopoda.dev/integrations/mcp.md).

## `octopoda whoami`

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

```bash theme={null}
octopoda whoami
```

## `octopoda logout`

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

```bash theme={null}
octopoda logout
```

## `octopoda update`

Installs the latest version of the CLI after checking its checksum and signature. See [Install and update the CLI](https://docs.octopoda.dev/cli/install.md#update).

## `octopoda version`

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.