Smoketest CLI

Run and manage Smoketest flows from your terminal.

Smoketest is an AI browser testing platform for plain-English smoke tests. Describe what a real user should do, run it in a browser, and get live status, recordings, transcripts, artifacts, and dashboard links.

The CLI is built for:

• Creating and running browser flows from your terminal
• Watching live run progress with a polished terminal UI
• Managing projects, subflows, environments, schedules, and runs
• Using Smoketest from your terminal, CI, and automation

Quick Start

Run the CLI without installing it globally:

npx @smoketest.sh/cli init

Or install it once:

npm install --global @smoketest.sh/cli
smoketest init

The installed commands are:

smoketest --help
st --help

smoketest init walks you through signup, browser login, email login, or importing an API key. After that, you can create a project, create a flow, and run it:

smoketest projects create --name "Production" --url https://example.com --use

smoketest flows create \
  --name "Homepage smoke test" \
  --url https://example.com \
  --description "Open the homepage, check the main CTA, and verify pricing is reachable"

smoketest flows run "Homepage smoke test" --watch

The --watch view shows the run status, current browser action, completed steps, and a dashboard link for the full recording.

What You Can Do

| Command | What it does | | --- | --- | | smoketest init | Set up the CLI with guided onboarding | | smoketest auth login | Sign in with browser device code, email code, or API key | | smoketest auth signup | Create an account with an email verification code | | smoketest projects ... | List, create, edit, delete, and select projects | | smoketest flows ... | Create, edit, schedule, run, and delete flows | | smoketest subflows ... | Create and manage reusable named flow snippets | | smoketest runs ... | List, inspect, watch, cancel, and rerun test runs | | smoketest env ... | Manage environment variables and secrets | | smoketest billing status | Check subscription and credit status | | smoketest profiles ... | Manage local credential profiles | | smoketest config ... | Manage local defaults | | smoketest completion ... | Print shell completion setup for zsh, bash, or fish |

Use smoketest <command> --help anytime for exact flags and examples.

Common Workflows

Sign In

smoketest init

For CI or automation, import an existing API key:

smoketest auth login --api-key smkt_...

For local use, prefer the interactive prompt so the key is not saved in shell history:

smoketest auth login

Create a Project

smoketest projects create --name "Marketing site" --url https://smoketest.sh --use
smoketest projects list

--use saves the project as your local default, so future commands can omit --project.

Create a Flow

smoketest flows create \
  --name "Pricing page smoke test" \
  --url https://smoketest.sh \
  --description "Open the homepage, go to pricing, and confirm plans are visible"

You can also read a longer description from a file:

smoketest flows create \
  --name "Signup smoke test" \
  --url https://smoketest.sh \
  --description @flows/signup.md

Create a Subflow

smoketest subflows create \
  --name "Log in" \
  --description "Open login, enter credentials, submit, and verify the dashboard"

Use --description @flows/login.md for longer markdown, or --editor to edit the subflow payload before creating it. Subflows are project-scoped. In the app, type / on a blank line in a flow description and select the subflow by name.

Run and Watch

smoketest flows run "Pricing page smoke test" --watch
smoketest flows run "Pricing page smoke test" --url https://preview-smoketest.vercel.app

Or run first and attach later:

smoketest flows run "Pricing page smoke test"
smoketest runs watch <run>

To run every flow with a project tag:

smoketest flows run --project "Production" --tag Smoke
smoketest flows run --project "Production" --tag Smoke --url https://staging.example.com

Grouped tag runs print the created run IDs. Use smoketest runs watch <run> to attach to one run from the group.

Manage Environments

Plain variables can be passed as KEY=value:

smoketest env create --name staging --var BASE_URL=https://staging.example.com

Secrets can be entered through a masked prompt:

smoketest env set <env> API_TOKEN --secret

Use JSON Output

Most resource commands support --json for scripts:

smoketest flows list --json
smoketest flows list --project "Production" --tag Smoke --json
smoketest runs get <run> --json

JSON mode is non-interactive. It skips prompts, spinners, confirmations, and live Ink UI.

IDs and Names

Human-readable tables show short 8-character IDs. Commands accept:

• Full UUIDs
• Short IDs, when they match exactly one resource
• Exact names, when the command supports name resolution

Examples:

smoketest projects get 4fa56a33
smoketest flows run "Homepage smoke test" --watch

Local Profiles

The CLI supports multiple local profiles:

smoketest profiles list
smoketest profiles use production
smoketest auth login --profile staging

Credentials are stored in the OS keychain. Non-secret profile metadata is stored in the local user config directory.

Configuration

Useful environment variables:

| Variable | Purpose | | --- | --- | | SMOKETEST_API_KEY | Use an API key without reading keychain state | | SMOKETEST_API_URL | Override the API origin | | SMOKETEST_CONFIG | Override the local profile config path | | SMOKETEST_ALLOW_INSECURE_API_URL | Allow non-HTTPS API URLs outside localhost |

The production API is:

https://api.smoketest.sh

Non-HTTPS API URLs are refused unless they are localhost. Use --allow-insecure-api-url only for trusted non-production endpoints.

Safety Notes

Prefer interactive prompts for API keys and secret values. Passing secrets in command arguments is useful for automation, but those values can be captured by shell history, process lists, terminal logs, or CI output.

This is allowed for automation:

smoketest auth login --api-key smkt_...
smoketest env set <env> API_TOKEN=value --secret

This is better for local interactive use:

smoketest auth login
smoketest env set <env> API_TOKEN --secret

For @file flow descriptions, sensitive-looking filenames such as .env or files containing secret, token, credential, password, or api-key require confirmation, or --yes in automation.

Shell Completion

smoketest completion zsh
smoketest completion bash
smoketest completion fish

Follow your shell's instructions to add the printed completion snippet to your shell config.

Links

• Website: smoketest.sh
• API: api.smoketest.sh
• Docs: docs.smoketest.sh

License

The Smoketest CLI is provided under the Smoketest CLI License.