Skip to content

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: 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>.

Terminal window
./.taskless/bin/cli.mjs info

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.

--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.

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>.