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:

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.

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

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:

octopoda scan --instructions "New: team invites in app/api/invites. Check who can invite and accept."

See the CLI commands reference for every flag.

​

Scan a repository from the web app

You need the Octopoda GitHub App installed on the repository first.

1. Open New scan

   Select New scan at the top of any page in 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.

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.

​

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.
• No plan. Start a plan or trial at 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.