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

# Run a code scan from the CLI or the web app

> Start an Octopoda code scan of a project folder with the CLI, or of a GitHub repository branch from the web app, and follow it until it finishes.

A code scan tests a whole project: Octopoda copies the code into a private sandbox, runs it, and reports what it can prove. You can start one from the CLI on any folder, or from the web app on any branch of a repository you connected through GitHub. Each code scan uses 5 credits and runs for up to 30 minutes.

## Scan a folder with the CLI

Run `octopoda scan` in your project, or pass the folder:

```bash theme={null}
octopoda scan ./my-app
```

The CLI packs the project, uploads it and starts the scan. In a git repository it includes what git tracks plus new files that are not ignored; elsewhere it includes the folder without dependency and build folders. It always leaves out `.env` files and private keys. See [Choose what gets scanned](https://docs.octopoda.dev/scanning/excluding-files.md).

The CLI then follows the scan and prints each stage and each finding as it is proven:

```text theme={null}
Packing /Users/you/code/my-app…
Uploading 214 files (1.8 MB)…
Scan #3 started (5 credits). https://app.octopoda.dev/scans/scn_…
You can press Ctrl+C at any time. The scan keeps running.
• Starting a private sandbox
• Preparing
• Exploring
```

Press **Ctrl+C** to stop following; the scan keeps running and you can check it with `octopoda status`.

### Useful flags

| Flag | What it does |
| - | - |
| `--instructions "<text>"` | Gives the scan extra guidance, such as what changed or what to focus on. |
| `--no-wait` | Starts the scan and returns right away with its number and link. |
| `--json` | Prints the result as JSON. |
| `--fail-on <level>` | Exits with code 1 if a finding at or above `critical`, `high`, `medium` or `low` is proven. Use it in CI. |

For example, to point the scan at a feature you just built:

```bash theme={null}
octopoda scan --instructions "New: team invites in app/api/invites. Check who can invite and accept."
```

See the [CLI commands reference](https://docs.octopoda.dev/cli/commands.md#octopoda-scan) for every flag.

## Scan a repository from the web app

You need the [Octopoda GitHub App](https://docs.octopoda.dev/integrations/github-app.md) installed on the repository first.

**1. Open New scan**

Select **New scan** at the top of any page in [app.octopoda.dev](https://app.octopoda.dev), or **Scan now** next to a repository.

**2. Pick the repository and branch**

Choose the **Repository** and the **Branch**. The default branch is selected first.

**3. Start the scan**

The dialog shows the cost and your balance after the scan. Select **Start scan**. The scan page opens and updates as the scan runs. You can leave the page; the scan keeps going.

> [!TIP]
>
> A full scan of a repository's default branch also re-tests the findings that are still open there. Any that can no longer be reproduced are marked fixed automatically. See [Triage findings](https://docs.octopoda.dev/findings/triage.md).

## When a scan cannot start

* **Not enough credits.** The scan needs 5 credits. Top up on the **Billing** page, or wait for your plan to renew. See [Plans and credits](https://docs.octopoda.dev/billing/plans-and-credits.md).
* **No plan.** Start a plan or trial at [app.octopoda.dev/start](https://app.octopoda.dev/start).
* **A payment failed.** Scans are paused until you update your card on the **Billing** page.
* **Other scans are running.** The scan waits in the queue and starts when one of your running scans finishes. Your plan sets how many run at once.


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