← CLI & REST API

Command-line interface (CLI)

The willet CLI exposes the same operations as the MCP tools, scriptable from any shell.

Install

The CLI is published to npm and needs Node.js 20 or newer.

npm install -g @willet/cli

The installed binary is willet. It talks to Willet Cloud by default: https://willet.bgenc.dev.

Log in (Willet Cloud)

For interactive use, log in through the browser. This opens a device-authorization page and stores a short-lived token under ~/.willet/.

willet login

Once approved, confirm the active identity:

willet whoami

Clear stored credentials with willet logout.

Use an API secret (scripts, CI, self-hosted)

For unattended use, skip the browser login and provide a secret in WILLET_API_TOKEN.

export WILLET_API_TOKEN=... willet whoami
  • Scope is either user (every project you can access) or project (a single project).
  • Access level is read (read-only) or read_write (full access).
  • WILLET_API_TOKEN takes precedence over a stored login and is never written to disk.

Target a self-hosted server

Point the CLI at your own Willet server in any of three ways (highest precedence first):

  • --api-url <url> a global flag on any command
  • WILLET_API_URL an environment variable
  • apiUrl an apiUrl field in ~/.willet/config.json

Self-hosted servers don't support willet login; authenticate with WILLET_API_TOKEN set to a user secret from the server's config file.

Output & scripting

  • --json prints raw JSON instead of a human summary; pipe it to a tool like jq.
  • -p <projectId> most ticket commands need a project UUID.
  • the tags flag is space-separated, not comma-separated: --tags backend perf
willet --json ticket create "Set up CI" -p $PROJECT --type chore --tags ci infra

Command reference

Commands are grouped by resource. Each group has its own subcommands:

GroupSubcommands
willet ticketlist, search, get, create, update, delete, start, complete, cancel, reopen, comment, link, unlink, graph, tags
willet projectlist, create, delete, restore, set-key-prefix, stats, members
willet orglist, create, update, delete, members
willet githublist, link, unlink
willet renderboard, dependency-graph

See the exact flags for any command with willet <group> --help.

Exit codes

Scripts can branch on the process exit code:

0Success
1Generic or network error
2Authentication failed (401)
3Forbidden (403), e.g. a read-only secret used for a write
4Not found (404)

Next

Everything the CLI does, it does over the REST API. Use the API directly when you'd rather not shell out.

REST API reference →