Every command

Setting up

cue discover

Look at a repository and say what Cue could learn from it. It only reads: it writes nothing, and ends with the commands that would act on what it found.

npx @wiluszdamian/cue discover
npx @wiluszdamian/cue discover --source ../my-app
npx @wiluszdamian/cue discover --json

It reports the Playwright config (read as text, never run), how many spec files there are, how many page objects, what the product’s source could tell Cue (test ids, routes, OpenAPI endpoints, labels, each with a count), which coding agents and instruction files it can see, and what is already set up here. --source points at the product when it is not this repository. init starts its plan with one line of the same.

cue init

Sets up a project. Shows you the plan first and waits for a yes. Without a terminal it applies nothing unless you pass --yes.

npx @wiluszdamian/cue init
npx @wiluszdamian/cue init --bare
npx @wiluszdamian/cue init --yes

cue doctor

Checks everything is wired up. Every problem comes with the command that fixes it.

npx @wiluszdamian/cue doctor
npx @wiluszdamian/cue doctor --ci
npx @wiluszdamian/cue doctor --offline

--ci fails the build when there are errors. --offline skips anything that needs the network. --source <path> says where the product source is, if it is not here.

Besides the setup, it looks at whether the notes in .agent-kb can be believed. A healthy knowledge base is one line; each problem adds one, with its fix:

Only an unreadable file is an error, because it is knowledge the tools cannot use at all. The rest are warnings: they say how far to trust the notes, and a team that has to silence warnings to ship stops reading them.

cue add / remove / list

Manage which assistants are set up.

npx @wiluszdamian/cue add cursor
npx @wiluszdamian/cue remove cursor
npx @wiluszdamian/cue list

Learning your app

cue survey <url>

Visit a page and write down what is on it.

npx @wiluszdamian/cue survey http://localhost:3000/login
npx @wiluszdamian/cue survey http://localhost:3000/login --from snapshot.txt

--from reads a snapshot captured elsewhere — useful when the environment needs credentials this machine does not have.

Surveying a live page needs @playwright/cli. It is found in the project’s node_modules, then on PATH; --playwright-cli <path> points at a specific copy. It is never run through a shell, so URLs with & or % arrive intact.

Looking at some pages again

You rarely need the whole app again. Name the pages, or let Cue pick them:

npx @wiluszdamian/cue survey --route /login,/admin/settings/security --base-url http://localhost:3000
npx @wiluszdamian/cue survey --stale --base-url http://localhost:3000
npx @wiluszdamian/cue survey --affected-by main..HEAD --base-url http://localhost:3000 --source ../my-app
npx @wiluszdamian/cue survey --stale --base-url http://localhost:3000 --dry-run

It shows the plan first, with the reason for each page. A page with a parameter (/items/[id]) is skipped and says why: survey a real URL for it. One page failing does not stop the others; the run fails if any did. --action is not implemented yet.

cue extract --source <path>

Reads the product source into .agent-kb/product: test ids, routes, endpoints from an OpenAPI document, and the labels in translation catalogues (nested JSON and YAML keep their full dotted keys, such as auth.login.submit).

It also reads the tests and page objects that are already there. Every getByRole with a plain role and name becomes a locator on the page the test was on, and each public page object method that uses locators becomes an action (changePassword is “change password”). All of it is recorded as inferred, citing the file and line: a test can be dead or failing, so it is evidence and not proof. A survey that sees the same element raises it; the tests alone never can.

npx @wiluszdamian/cue extract --source .

cue locator <description>

Look up how to point at something.

npx @wiluszdamian/cue locator "log in button"
npx @wiluszdamian/cue locator "submit" --route /checkout

cue context <task>

What is known that bears on a task, in one answer that fits a token budget. The same answer the get_context tool gives an agent, which is what makes it useful for seeing what an agent was told.

npx @wiluszdamian/cue context "test changing the password"
npx @wiluszdamian/cue context "add an item" --route /items --max-tokens 600

It picks the page the task is about, the elements on it that match, the endpoints and vocabulary it mentions, the rules a test must follow, and how recent each part is. Nothing is asked of a model: the same task over the same notes gives the same answer. When the budget is tight it drops a second page, then vocabulary, then endpoints, then elements, and never the rules or the ages. A task that matches nothing says status: unknown and what to run to find out. --max-tokens takes 200 to 3000 (default 1200).

cue check

Check that the locators in your tests name things the notes know about.

npx @wiluszdamian/cue check
npx @wiluszdamian/cue check tests/login.spec.ts
npx @wiluszdamian/cue check tests --ci
npx @wiluszdamian/cue check --ci=strict --format github

With no arguments it looks at test files (*.spec.ts, *.test.ts) and any file with an // cue-route: /login comment, which is how a page object says which page it is on. Given a directory it takes everything TypeScript in it; given a pattern, whatever matches.

Each locator comes back as one of:

Undecidable locators are always counted and listed. They are not judged, and nothing here pretends otherwise.

Without --ci the exit code is always 0. With nothing in .agent-kb, it says to run extract and survey rather than listing every locator as unknown.

cue verify

Check the notes still match the real app, and say plainly what was not checked. (verify-map is the old name and still works, with a warning.)

npx @wiluszdamian/cue verify --base-url http://localhost:3000
npx @wiluszdamian/cue verify --base-url $STAGING_URL --route /login,/signup
npx @wiluszdamian/cue verify --base-url $STAGING_URL --ci=strict
npx @wiluszdamian/cue verify --base-url $STAGING_URL --refresh
npx @wiluszdamian/cue verify --json

The verdict is one of PASS, PARTIAL, NOT VERIFIED, FAIL or EMPTY. Only PASS says the notes match the app, and only when every page was checked.

Without --ci the exit code is always 0.

Staying current

cue sync

Bring your project’s copy of the rules up to date. Shows a diff first.

npx @wiluszdamian/cue sync
npx @wiluszdamian/cue sync --check

--check reports and changes nothing, which is what you want in CI.

Understanding a rule

cue explain <rule>

Why a rule exists and what to write instead.

npx @wiluszdamian/cue explain
npx @wiluszdamian/cue explain no-hard-waits

With no rule name, it lists them all.

Removing it

cue uninstall

Takes out everything init put in, using a record of exactly what that was. Anything you edited is kept and reported.

npx @wiluszdamian/cue uninstall

Not built yet

These are planned and named in the docs. They do not exist yet, and Cue says so rather than pretending:

• extract — read your app’s source code for extra detail
• inspect — audit an existing test suite
• from-openapi — generate API tests from a spec
• upgrade — move a project to a newer version