CLI Quickstart

Install the CLI and run your first suite from the terminal.

Prefer the terminal? The cofactor CLI runs tests, queries issues, and installs agent skills — so you (and a coding agent like Claude) can author and run tests without leaving your editor. This guide takes you from an empty terminal to a passing test in five steps.

Don't want to read this? Copy this prompt and give it to your agent:

Set up Cofactor with your agent

Or read on to do it yourself.

01Install the CLI

Install it globally with npm (or Bun):

bash

npm install -g @runcofactor/cli
# or
bun add -g @runcofactor/cli

Confirm it's on your path:

bash

cofactor --version

02Log in

Authenticate once. cofactor login opens your browser to approve the session, then saves an org-scoped token to ~/.config/cofactor-cli/auth.json:

bash

cofactor login

Approve the CLI session from your browser to finish logging in

A few flags worth knowing:

--org <name> — pick an organization if you belong to more than one.
COFACTOR_API_TOKEN — set this instead of cofactor login for CI and other non-interactive environments.

03Install your first skills

A skill is a SKILL.md file that teaches Claude Code (or Codex, or Copilot) how to do one thing well — here, how to author and run Cofactor tests. cofactor skill install auto-detects your agent and drops the skill into your project (use --personal to install into ~/.claude instead).

See what's available, then install the two you'll use to write tests:

bash

cofactor skill list

cofactor skill install test-cases        # author tests as .cofactor.md specs
cofactor skill install browser-testing   # drive the app interactively to verify

That's it — next time you open Claude Code in this project, both skills are live.

04Write your first test with Claude

You now have two complementary ways to test with Claude, side by side.

Author a test (test-cases)

Ask Claude, in plain language, to write a test for a real journey through your app:

"Write a test that signs in and confirms the dashboard loads."

The test-cases skill turns that into a .cofactor.md spec — one coherent journey per file. Validate it offline, compile it into a live workflow, then run it:

bash

cofactor spec validate dashboard-loads.cofactor.md   # lint it offline
cofactor spec compile  dashboard-loads.cofactor.md   # compile → a flow (prints its id, saved to the file)
cofactor workflow run <id>                           # run that flow and stream results

Verify interactively (browser-testing)

When you'd rather watch it happen, ask Claude to drive the app and check the result:

"Open the app, sign in, and tell me whether the dashboard renders."

The browser-testing skill runs cofactor session under the hood — launching a real browser, clicking through your flow, and reporting back what it saw. Great for exploring a journey before you commit it to a spec.

05The loop you just learned

Install once, log in once — then it's the same short loop every time: ask Claude for a test, compile it, run it. Each green run is a journey you'll never have to check by hand again.

06Next steps

Prefer the UI? Walk the Quickstart in the app instead.
Add a login credential so your tests can act as a signed-in user.
Wire your suite into CI — see Using the CLI in CI.

07Troubleshooting

Hitting a corporate proxy or TLS error? Run cofactor auth doctor to diagnose it — it checks your connection, certificates, and auth state, and prints what to fix.