Command reference

This table is generated from the CLI's own command definitions, so it always matches the current release. Run bucky <command> --help for a command's flags, or bucky --json agent-context for the full machine-readable contract (arguments, enums, bounds, and mutation safety).

Start with bucky --json agent-context --index for a compact list of canonical commands and groups. Fetch full contracts with --group "projects share-links" or --command "projects create". These selectors are mutually exclusive. Groups match a canonical namespace and its descendants. Command selectors match an exact canonical name or an unambiguous declared alias and return the canonical contract. Whitespace is normalized; empty, unknown or ambiguous selectors return INVALID_ARGUMENT with exit code 2.

The outer JSON envelope remains schema version 1. No-selector agent-context keeps its existing full document at schema version 1. The new index is independently versioned with documentType: "index" and schemaVersion: 1; it contains command summaries, kinds and authentication classes, canonical group names, workflows (root commands by workflow, with entryPoints first — the same groups as root --help and the palette) compatibility (empty since 0.14.0) and removed (removed command paths mapped to the command to use instead), without per-command options, notes or shared globals. Scoped documents use documentType: "scoped" and schemaVersion: 1, with selection, complete selected commands, and the shared output and transport contracts. All modes run offline without credentials, omit secret-bearing options and respect public-build command availability. capabilities retains its distinct legacy projection.

• Kind — read and write call the Bucky API; read-local and write-local only touch files on your machine.
• Auth — product needs a signed-in Bucky user (Authentication); none runs without signing in.
• Every write supports --dry-run. See Safe writes.

Commands removed in 0.14.0Copy Anchor Link

0.14.0 removed the old command paths below. Running one does nothing and exits 2 with error code COMMAND_MOVED; the message and error.details.replacements name the command to use instead. agent-context lists the same mapping under removed. Installed 0.13.0 and earlier binaries keep the old paths until you update.

bucky help with no path now shows root help, the same as bucky --help.

These shortcuts stay: tasks complete (same request as tasks update --status completed), references pin, unpin, exclude, include, set-note and clear-note (each is one field of references update, with its own mutation ID), and the opportunities screen alias of opportunities assess.

Receipts written before 0.14.0 stay readable and undoable. operations show prints their recovery command with the new path, and --retry-operation still works because receipts are matched by mutation ID, not by command path.

Contact search paginationCopy Anchor Link

bucky contacts list --q "planner" --limit 20 --offset 20 requests a page from the existing contacts API. The default limit is 20, the maximum is 200, and offsets are nonnegative integers. Results sort by name, then contact ID. The count field is the returned page size; total is the exact number of matching contacts owned by the caller, or null when unavailable. hasMore is null when continuation is unknown; use nextOffset when it is supplied.

Pagination is stable while the directory is unchanged. Inserts, deletes, or renames between requests can shift page boundaries, causing repeats or omissions. Restart the traversal if the directory changes during a scan.

Older servers without pagination metadata support first-page reads with unknown totals. A nonzero offset fails with API_CONTRACT_MISMATCH when the server does not confirm that offset, so page one cannot be mistaken for a later page.

Account preference reads and writesCopy Anchor Link

Use account locale get and account notifications get for read-only access. Set a locale with account locale set fr, or update notification preferences with account notifications set --input preferences.json. Both setters support --dry-run and require confirmation (--yes for JSON or non-interactive calls). Notification input must contain a nonempty preferences object mapping known push category IDs to booleans.

Help and suggestionsCopy Anchor Link

bucky help <command path> renders the same offline text as <command path> --help, including deep paths and registered command aliases. It does not run the selected command, require its positional arguments, authenticate, or make network requests. Nested pages show their own relevant examples; starter examples appear only at the root. Unknown paths fail with INVALID_ARGUMENT (exit 2) and point to the nearest valid parent's help. Help-path shell completion lists commands rather than resolving project IDs or other resources.

Use bucky suggest for bounded contextual recommendations and bucky palette for interactive discovery. bucky help without a path shows root help. Contextual recommendations may use bounded read probes when signed in. In JSON mode, suggest returns { context, suggestions, profilePrefix }. Command-path help stays plain text even with --json, matching the conventional --help option; JSON errors retain the standard envelope.