---
title: "CLI Reference | ShipSafe"
description: "Every ShipSafe CLI command, flag, and output format. Scriptable scans, JSON output, CI-friendly exit codes."
doc_version: 2026-10-05
last_updated: 2026-10-05T09:31:56.818Z
canonical: https://ship-safe.co/docs/cli
---

# CLI Reference | ShipSafe

● CLI Reference

# Command line. Receipts.

Scriptable scans, JSON output, exit codes your CI already understands. No daemon, no config required.

▸ Install

## Install

No install needed. Run via npx:

TERMINAL

Copy

```bash
npx @ship-safe/cli <command>
```

Or install globally: `npm i -g @ship-safe/cli`

▸ Authentication

## Authentication in CI

On your own machine, `shipsafe login` stores a token in `~/.shipsafe/token.json`. A CI runner has no such file, so pass the token in the environment instead:

TERMINAL

Copy

```bash
SHIPSAFE_TOKEN=<your token> npx @ship-safe/cli scan . --ci
```

`SHIPSAFE_TOKEN` takes precedence over a stored login, and is never written to disk. Requires CLI 1.2.0 or later — earlier versions ignored it.

**Without a paid token, a CI scan runs the pattern checks only.** The AI deep scan — broken auth, IDOR, privilege escalation and the other issues that need reasoning across files — does not run, and those issues are not looked for. In `--ci` mode the CLI prints which depth actually ran to stderr, so a green pipeline never quietly stands in for a scan that did not happen.

▸ Commands

## Commands

Seven commands. Most days you only need `scan`.

▸ SCAN

## scan

Scan a directory or file for security vulnerabilities.

TERMINAL

Copy

```bash
shipsafe scan [path]
```

### ▸ Arguments

| \[path\] | Path to scan. Defaults to current directory ("."). |
| -------- | -------------------------------------------------- |

### ▸ Flags

| \-o, --output <format>  | Output format: table (default), json, or sarif.                                                          |
| ----------------------- | -------------------------------------------------------------------------------------------------------- |
| \-s, --severity <level> | Minimum severity to report: critical, high, medium, low (default: low).                                  |
| \--ci                   | CI mode. Exits with code 1 if findings match the severity threshold. Use in GitHub Actions to block PRs. |
| \--upload               | Upload results to your ShipSafe dashboard. Happens automatically when logged in.                         |
| \--api-url <url>        | API URL for self-hosted ShipSafe. Default: https://ship-safe.co                                          |

### ▸ Examples

Scan current directory

TERMINAL

Copy

```bash
npx @ship-safe/cli scan .
```

Only show high/critical findings

TERMINAL

Copy

```bash
npx @ship-safe/cli scan src/ --severity high
```

JSON output for scripting

TERMINAL

Copy

```bash
npx @ship-safe/cli scan . --output json
```

CI mode: fail only on critical

TERMINAL

Copy

```bash
npx @ship-safe/cli scan . --ci --severity critical
```

▸ LOGIN

## login

Log in to your ShipSafe account. Opens your browser for authentication. Once logged in, scan results automatically sync to your dashboard.

TERMINAL

Copy

```bash
shipsafe login
```

### ▸ Flags

| \--api-url <url> | API URL for self-hosted ShipSafe. Default: https://ship-safe.co |
| ---------------- | --------------------------------------------------------------- |

### ▸ Examples

Log in (opens browser)

TERMINAL

Copy

```bash
npx @ship-safe/cli login
```

▸ LOGOUT

## logout

Clear your stored authentication token.

TERMINAL

Copy

```bash
shipsafe logout
```

▸ WHOAMI

## whoami

Show your current login status and email.

TERMINAL

Copy

```bash
shipsafe whoami
```

▸ INIT

## init

Create a .shipsafe.yml configuration file in the current directory with sensible defaults.

TERMINAL

Copy

```bash
shipsafe init
```

▸ IGNORE

## ignore

Suppress a rule in future scans. Adds it to .shipsafeignore. Suppressed findings still appear in the dashboard as "suppressed" but won't block CI.

TERMINAL

Copy

```bash
shipsafe ignore <rule-id>
```

### ▸ Arguments

| <rule-id> | Rule ID to ignore (e.g., secrets/generic-api-key). |
| --------- | -------------------------------------------------- |

### ▸ Flags

| \-r, --reason <reason> | Why this rule is being suppressed. Stored as a comment in .shipsafeignore. |
| ---------------------- | -------------------------------------------------------------------------- |

### ▸ Examples

Ignore with reason

TERMINAL

Copy

```bash
npx @ship-safe/cli ignore secrets/generic-api-key -r "Test API key, not real"
```

Ignore without reason

TERMINAL

Copy

```bash
npx @ship-safe/cli ignore xss/dangerously-set-html
```

▸ UNIGNORE

## unignore

Re-enable a previously suppressed rule. Removes it from .shipsafeignore.

TERMINAL

Copy

```bash
shipsafe unignore <rule-id>
```

### ▸ Arguments

| <rule-id> | Rule ID to unignore. |
| --------- | -------------------- |

### ▸ Examples

Re-enable a rule

TERMINAL

Copy

```bash
npx @ship-safe/cli unignore secrets/generic-api-key
```

[← PreviousFix it for me, with a receipt](https://ship-safe.co/docs/fix-it-for-me)[Next →MCP Server](https://ship-safe.co/docs/mcp)

## Sitemap

Every page of this site, in markdown: [https://ship-safe.co/sitemap.md](https://ship-safe.co/sitemap.md)