Command reference

Every CLI command and what it does.

A map of the CLI, grouped by what you're trying to do. Run any command with --help (or bare) for its full sub-commands and flags.

01Conventions

--json — most read commands emit raw JSON for scripting and agents.
--env <prod|dev|local> — target environment for commands that support it.
Flags over prompts — every interactive prompt has a flag equivalent, so agents and scripts can drive any command non-interactively.
cofactor and canary are the same CLI — one binary per brand name; commands and flags are identical.

02Author tests

Command	What it does
`cofactor spec`	Validate and compile `.cofactor.md` test specs into flows
`cofactor workflow`	Inspect, create, sync, run, approve, promote, and pause flow definitions
`cofactor record`	Record browser interactions to author from a real session

Start with the CLI Quickstart and the Cofactor spec format.

After a flow passes validation, use cofactor workflow approve <workflowId> to record human sign-off and cofactor workflow promote <workflowId> to include it in suites. Use cofactor workflow pause <workflowId> to keep an approved flow out of suites. cofactor workflow publish remains a deprecated alias for promotion and requires approval first. cofactor spec --publish has been removed; compile or sync first, then approve and promote deliberately.

03Run tests

Command	What it does
`cofactor test-suite`	Run suites and query executions (`run`, `list`, `get`, `steps`)
`cofactor debug <workflowId>`	Replay a flow in a local headed browser, step by step

See Running your tests and Using the CLI in CI.

04Schedule & alert

Command	What it does
`cofactor schedule suite`	Schedule recurring test-suite runs (`create`, `edit`, `pause`, `resume`, `delete`, `run`, `runs`)
`cofactor alert`	Notify-only rules that Slack/email on suite results (`create`, `edit`, `pause`, `resume`, `delete`, `run`)

A schedule targets a named suite (--suite-id), a tag (--tag), or every published flow (--all-published), on a cadence set with --schedule "every weekday at 9am", --cron, --at HH:mm, or --every 30m. An alert fires after a suite completes (or on the same cadence flags) and routes to --slack <channelId> and/or --email <addr>, narrowed with --when failure|success and optional --filter "field:op:value". Both manage the same automation rules as Settings → Automations; use pause/resume to toggle one without deleting it.

05Drive a browser

Command	What it does
`cofactor session`	Start and control local browser sessions — snapshot, click, type, multiple named sessions, `--attach-real-chrome`
`cofactor local`	Set up and manage local-environment testing (init, start, login)

See Testing locally.

06Environments, data & access

Command	What it does
`cofactor property`	List and create applications; link GitHub repos
`cofactor sandbox`	Author, verify, and provision sandbox templates and instances
`cofactor credential`	List, create, update, and test login credentials
`cofactor persona`	Manage named roles and their credential bindings per application
`cofactor attachment`	Upload and manage file fixtures
`cofactor tag`	Create and assign tags (suites run by tag)
`cofactor api-catalog`	Manage API catalog sources and endpoints

See Setting up a sandbox and Credentials & login.

07Investigate results

Command	What it does
`cofactor issues`	Search, read, close, and reopen issues
`cofactor triage`	Read AI triage clusters for a suite execution (`get`, `failures`, `wait`)
`cofactor workflow debug <runId>`	Inspect a run's recorded evidence — steps, thoughts, cache, traces

See Triaging a failure.

08Agent tooling

Command	What it does
`cofactor skill`	Install and update agent skills (`browser-testing`, `debug-run`, `test-cases`, …)
`cofactor mcp`	Start the MCP server (stdio) for MCP-capable agents
`cofactor install`	Install the MCP server into Claude, Cursor, and other agents

See Driving Cofactor from your coding agent.

09Account

Command	What it does
`cofactor login`	Browser-approved authentication (details)
`cofactor orgs`	List organizations; pick with `login --org`
`cofactor auth doctor`	Diagnose auth and proxy issues