CLI Reference

ShipTested provides 9 commands for generating tests, managing authentication, and viewing project data. This page documents every command, its flags, and usage examples.

All commands can be run with shiptested [command] if installed globally, or npx shiptested [command] without a global install.

init#

Initialize a ShipTested configuration file in your project. Analyzes your codebase and creates shiptested.config.ts with smart defaults based on your language, framework, and test runner.

Usage#

shiptested init [path] [--force]

Arguments and Flags#

Example#

# Initialize in the current directory
shiptested init

# Initialize in a specific directory
shiptested init ./my-project

# Overwrite an existing config
shiptested init --force

If a config file already exists and --force is not set, the command exits with a warning. The generated config includes sensible exclude patterns (node_modules, dist, build, test files) and auto-detects whether to colocate tests with source files.

login#

Authenticate with ShipTested via GitHub OAuth. Opens your browser to the GitHub authorization page, starts a local server to receive the callback, and saves credentials to ~/.shiptested/credentials.

Usage#

shiptested login [--api-url <url>]

Flags#

Example#

# Standard login
shiptested login

# Login against a custom API
shiptested login --api-url http://localhost:3002

The login flow has a 2-minute timeout. If you are already authenticated, the command displays your current session info and exits. Credentials include your token, email, and expiration date.

For CI/CD environments, use the SHIPTESTED_API_KEY environment variable instead of OAuth. See the CI/CD Integration guide.

logout#

Sign out of ShipTested. Removes the credentials file at ~/.shiptested/credentials.

Usage#

shiptested logout

This command takes no arguments or flags.

Example#

shiptested logout
# Output: Signed out. Credentials removed.

generate#

The main command. Generates test suites for your project files using AI, runs them locally, and iterates until they pass. Results are reported to the dashboard automatically.

Usage#

shiptested generate [path] [flags]

Arguments and Flags#

Exit Codes#

Examples#

# Generate tests interactively
shiptested generate

# Test specific files
shiptested generate --files src/utils/helpers.ts,src/lib/api.ts

# Test all files with 5 iterations
shiptested generate --all --max-iterations 5

# CI mode: only changed files, 80% threshold
shiptested generate --ci --changed-only --threshold 80

# Get JSON output for scripting
shiptested generate --json --all

In interactive mode (the default), you are presented with a list of testable files to select from. Use --ci or --all to skip the selection prompt.

analyze#

Dry run that scans your project and displays testable files grouped by type, along with complexity ratings. No tests are generated or executed.

Usage#

shiptested analyze [path] [--json]

Arguments and Flags#

Example#

$ shiptested analyze

  Detected: TypeScript + React | tests: vitest | npm

  components (4):
    src/components/Button.tsx  (low)
    src/components/Modal.tsx   (medium)
    src/components/Form.tsx    (medium)
    src/components/Table.tsx   (high) [has tests]

  utilities (2):
    src/lib/format.ts    (low)
    src/lib/validate.ts  (medium)

  Summary:
    Testable files: 6
    Already tested: 1
    Missing tests:  5

Use --json to get the full analysis object, which includes detected language, framework, test framework, package manager, module system, and the complete list of testable files with their types and complexity.

coverage#

Runs your existing test suite with coverage enabled and displays per-file coverage results. Supports both Vitest and Jest coverage reporters.

Usage#

shiptested coverage [path] [--json]

Arguments and Flags#

Example#

$ shiptested coverage

  Test framework: vitest
  Running tests with coverage...

  +-----------------------------+----------+----------+----------+----------+
  | File                        | Lines    | Stmts    | Funcs    | Branch   |
  +-----------------------------+----------+----------+----------+----------+
  | src/lib/format.ts           | 94.2%    | 94.2%    | 100.0%   | 85.7%    |
  | src/lib/validate.ts         | 78.6%    | 80.0%    | 66.7%    | 71.4%    |
  +-----------------------------+----------+----------+----------+----------+
  | Total                       | 86.4%    | 87.1%    | 83.3%    | 78.6%    |
  +-----------------------------+----------+----------+----------+----------+

  Overall line coverage: 86.4%

The command has a 5-minute timeout. It reads coverage data from the coverage/coverage-summary.json file generated by your test runner. If no JSON summary is found, the raw test output is displayed instead.

dashboard#

Opens your project dashboard in the default browser. The project slug is derived from the name field in your package.json, or falls back to the directory name.

Usage#

shiptested dashboard [path]

Arguments#

Example#

shiptested dashboard
# Opens https://app.shiptested.app/p/my-project

whoami#

Displays information about the currently authenticated user, including email, plan, GitHub connection status, and account creation date.

Usage#

shiptested whoami

This command takes no arguments or flags.

Example#

$ shiptested whoami

  Email:    dev@example.com
  Name:     Jane Doe
  Plan:     pro
  GitHub:   connected
  Since:    3/15/2026

If you are not authenticated, the command exits with an error and prompts you to run shiptested login.

usage#

Shows your current month usage stats and plan limits, including files used, remaining files, tokens consumed, and total runs.

Usage#

shiptested usage [--json]

Flags#

Example#

$ shiptested usage

  Plan:       pro
  Period:     March 2026

  Files:      42 / 200 (21%)
              [######                        ]
  Remaining:  158 files
  Tokens:     1,234,567
  Runs:       12

Use --json to get the raw usage object for scripting or integration with other tools. Requires a ShipTested account (not available with a direct Anthropic API key).

Next Steps#

• Configuration - customize config files, formats, and environment variables
• CI/CD Integration - automate test generation in your pipeline
• Troubleshooting - common issues and solutions