Taskless CLI
The Taskless CLI (@taskless/cli) manages rules, runs checks, and installs the agent skill. It ships as an npm package. You run the installer with npx, and it writes a project launcher, ./.taskless/bin/cli.mjs, that every later command runs through. Installing the CLI covers why.
For Humans and For Agents
Section titled “For Humans and For Agents”- For humans: run
npx @taskless/cli(no args) to install or update Taskless in this repository, then ask your coding agent to do the work. - For agents: the installed skill is a thin router. When an agent needs to act, it runs
./.taskless/bin/cli.mjs agent <topic>to fetch the canonical recipe (Goal, Preconditions, Steps, Schema, Errors, See Also) and follows it.
The docs site covers the human-facing surface. For the full machine-readable recipe behind any sub-command, run ./.taskless/bin/cli.mjs agent <topic>.
Quick Start
Section titled “Quick Start”./.taskless/bin/cli.mjs infoTopics
Section titled “Topics”Most CLI topics have a corresponding recipe. Run ./.taskless/bin/cli.mjs agent <topic> for the full text.
agent returns a recipe for an agent to follow; the commands below are what those recipes run.
Commands:
| Topic | Summary |
|---|---|
init |
The install with no prompts, for scripts and agents |
update |
Learn what an upgrade changed for existing rules, or record a reconciliation |
info |
Show CLI version, installed tools, and auth status |
detect |
Scan the repo for linters, languages, rule styles, CI, hooks, and host tools (offline) |
check |
Run rules against your codebase |
auth |
Manage authentication with taskless.io |
rule |
Create, improve, delete, restore, and roll back rules |
onboard |
Find and write starter rules from your project, then publish a report |
report |
Draft, publish, or delete an unlisted report on tskl.es of what your rules catch |
validate |
Check that a rule has the components its engine requires |
verify |
Run a rule’s fixtures, after validating the rule itself |
feedback |
Send feedback or a bug report, or answer or dismiss the rule survey |
share |
Show a QR code for taskless.io |
Running npx @taskless/cli with no sub-command in a terminal opens the installer.
Authoring recipes. Where a new rule is authored and routed, plus wiring checks into CI (see Authoring Rules):
These are recipe-only topics, reachable as ./.taskless/bin/cli.mjs agent <topic> rather than as bare commands.
| Topic | Summary |
|---|---|
route |
Decide which recipe authors a rule. Start here |
create-legacy-rule |
Author a rule in a linter the repo already uses; --tool=<name> for one linter’s own recipe |
create-sg-rule |
Author a local ast-grep rule over code (no login) |
create-vale-rule |
Author a local Vale rule over prose (no login) |
create-runtime-rule |
The runtime engine, and why it needs Taskless Cloud |
create-remote-rule |
Generate a rule via the Taskless service (login) |
improve-rule |
Iterate on an existing rule |
delete-rule |
Remove a rule and its fixtures |
recover-rule |
Restore an edited issued rule, or roll it back to an earlier revision |
ci |
Wire taskless check into your CI (see Continuous Integration) |
hooks |
Run taskless check from a git commit hook |
Run ./.taskless/bin/cli.mjs detect --json to see the repo scan detect produces, or ./.taskless/bin/cli.mjs agent detect for its recipe. Run ./.taskless/bin/cli.mjs agent (no args) for the live topic list.
The --anonymous Flag
Section titled “The --anonymous Flag”--anonymous is a top-level flag accepted on every command. It forces local-only behavior on rule create and rule improve, skipping the Taskless API. On check it skips runtime rules; your sg and vale rules still run, since they need no account either way. It is a no-op on most other commands and errors on auth login. Pass it to keep everything on-device without sending anything to taskless.io.
Error Output
Section titled “Error Output”When you pass --json and a command fails, the CLI emits a stable error shape with a code field (e.g., AUTH_REQUIRED, CLI_VERSION_MISMATCH, RULES_ENGINE_MISMATCH). Recipes can branch on this code without parsing prose. For the per-topic error catalog, see the Errors section in ./.taskless/bin/cli.mjs agent <topic>.