CLI
Use Bucky from the command line — installation, authentication, and common commands.
Install the latest promoted Bucky CLI release on macOS or Linux:
curl -fsSL https://raw.githubusercontent.com/markbucky/bucky/main/apps/bucky-cli/install.sh | shThe installer requires Node.js 24 or newer, verifies the release archive's
SHA-256 checksum, and installs without sudo under ~/.local/bin. To inspect
the installer before running it:
curl -fsSLo install-bucky.sh \
https://raw.githubusercontent.com/markbucky/bucky/main/apps/bucky-cli/install.sh
less install-bucky.sh
sh install-bucky.shSet BUCKY_VERSION=<version> to install a specific promoted version. Running
the installer again updates the CLI. It prints the exact user-local paths to
remove when uninstalling.
The TypeScript bucky CLI provides two deliberately separate command groups:
- Product commands act as a Bucky user through the existing application APIs.
- City commands wrap the reviewed municipality-onboarding scripts for operators.
From a repository checkout:
pnpm install
pnpm bucky -- --help
pnpm bucky -- doctornx build bucky-cli produces apps/bucky-cli/dist/bin.js. The package exposes
that file as the bucky binary.
Agent-friendly output
Pass the global --json option before the command for one deterministic
envelope:
pnpm --silent bucky -- --json capabilities
pnpm --silent bucky -- --json projects list --limit 5
pnpm --silent bucky -- --json city status --city us-il-chicagoSuccesses use { "ok": true, "data": ... }; failures include an error code and
an executable hint. Exit code 0 means success, 1 means a domain violation or
rejected operation, and 2 means invalid input or an infrastructure problem.
The CLI also respects NO_COLOR and BUCKY_NO_TUI. Human output uses one of
three terminal modes: machine (--json or piped stdout), human-interactive
(both stdin and stdout are TTYs), or human-static (CI, BUCKY_NO_TUI,
TERM=dumb, or non-interactive stdin). JSON and piped stdout never include
prompts, spinners, cursor controls, or ANSI progress frames.
Use pnpm's --silent option when consuming JSON from the repository script so
its script banner does not precede the envelope. The installed bucky binary
does not need this wrapper option.
Mutating commands support --dry-run. A dry run prints the intended HTTP
request or delegated command, a field-level preview, and whether the action is
undoable. It does not execute the mutation.
Non-interactive execution (--json, piped stdout, or CI) requires explicit
--yes after reviewing the same command with --dry-run. Interactive terminals
prompt with [y/N/edit] before executing.
Executed mutations write a pending secret-free receipt before the first
remote write, then update the same receipt id terminally
(completed / failed / cancelled / unknown). Inspect them with
bucky operations list and bucky operations show <receipt-id>. After an
ambiguous project create, resume with
bucky projects create --retry-operation <receipt-id> --yes (same intent
flags) so the original Idempotency-Key is reused. Identical payloads alone
never deduplicate. bucky undo <receipt-id> or bucky undo --last --yes
replays only tested inverses (project update, create, and archive). Chat turns
are not cross-invocation retry-safe.
Human output (without --json) is summary-first: one-line outcomes, then
decision-relevant key/value rows or width-aware tables. Pass --full before the
command to expand domain payloads, and --verbose to include redacted diagnostic
details on errors. Tables adapt to terminal width and fall back to pipe-safe
column | column lines on narrow screens. Semantic color is used for success,
warning, and failure states; set NO_COLOR or --no-color to disable it.
Errors print what happened, a likely cause when known, and an exact safe next
step. Suggested commands from fuzzy discovery may appear for unknown subcommands,
but are never executed automatically.
Output is compact by default to protect agent context windows. Knowledge search
omits large section bodies, project detail omits associations, and reference
lists default to 20 rows. Pass the global --full option before the command
when the complete payload is necessary:
pnpm --silent bucky -- --json --full projects get <project-id>
pnpm --silent bucky -- --json --full knowledge search --q "front setback"List responses retain pagination metadata. projects list and references list
accept --offset as well as --limit. Continue references list with the next
--offset while pagination.hasMore is true.
Network reads and safe idempotent writes retry twice by default (transport
retries inside one process). The global --timeout <seconds> defaults to 120
seconds and covers response headers plus complete JSON bodies. During
chat turn, the same value is a stream-idle timeout and resets whenever an
event arrives; --timeout 0 disables it. Do not wrap the CLI in another retry
loop: writes retry only when they carry an idempotency key. Cross-process
recovery uses --retry-operation <receipt-id>, not payload similarity.
Product authentication
Product commands require a real Supabase user JWT. They never open a browser.
The token is read from BUCKY_ACCESS_TOKEN first, then from the XDG config file
at ${XDG_CONFIG_HOME:-~/.config}/bucky/config.json.
The CLI currently signs in existing accounts only. New account registration, email confirmation, waitlist policy, and signup profile side effects remain in the Bucky web signup flow.
bucky --profile agent auth login
bucky --profile agent agent check \
--require projects:read,projects:create,chat:write,knowledge:readInteractive login prompts for the deployment, email, and a hidden password. It
defaults to https://buckybuild.com, discovers the deployment's browser-public
Supabase URL and anonymous key, and saves that public configuration in the
selected profile only after authentication succeeds. Remote origins require
HTTPS; loopback HTTP is supported for local development.
Dedicated agent profile
Named profiles isolate a coding agent's session from a developer's default
login. The agent profile is stored at
${XDG_CONFIG_HOME:-~/.config}/bucky/profiles/agent.json with user-only file
permissions.
Bootstrap it once without putting the password in shell history:
bucky --profile agent auth login
pnpm --silent bucky -- --profile agent --json auth status
pnpm --silent bucky -- --profile agent --json agent check \
--require projects:read,projects:create,chat:write,knowledge:readUse a dedicated product user with project-scoped membership. Do not provide the CLI with a Supabase service-role key or assume platform-admin access.
Automation and headless login
--json, CI, and non-TTY execution never prompt. Set BUCKY_EMAIL and
BUCKY_PASSWORD for a headless password exchange, or pipe existing access and
refresh tokens to
--access-token-stdin or --refresh-token-stdin. Secret-valued argv flags remain
available for compatibility but emit a deprecation warning; do not put secrets
in argv.
BUCKY_EMAIL=user@example.com BUCKY_PASSWORD=... bucky --json auth login
printf %s "$BUCKY_ACCESS_TOKEN" | bucky --json auth login --access-token-stdinWhen a required value is missing, headless mode returns one
AUTH_INPUT_MISSING JSON envelope instead of pausing.
Saved sessions automatically exchange their refresh token when the access token
is about to expire. Tokens supplied through BUCKY_ACCESS_TOKEN remain
caller-owned and are never refreshed or persisted.
Readiness and capability discovery
Prefer agent-context for the rich, versioned command introspection document
(arguments, enums, bounds, mutation/confirmation, execution modes). capabilities
remains a compatibility projection of the same CommandSpec source for one release.
agent check verifies the active profile with bounded reads:
pnpm --silent bucky -- --profile agent --json agent-context
pnpm --silent bucky -- --profile agent --json capabilities
pnpm --silent bucky -- --profile agent --json agent check
pnpm --silent bucky -- --profile agent --json agent check \
--require projects:read,projects:create,chat:write,knowledge:readThe accepted agent check --require tokens are projects:read,
projects:create, chat:write, and knowledge:read. A required write
capability succeeds only when the command is present in the local CLI and the
versioned server readiness endpoint confirms authorization. Each write probe
reports commandAvailable, authenticated, reachable, and authorized.
Missing or incompatible server support is unavailable and fails closed.
Readiness never creates a project, sends a chat message, initialises credits, or
otherwise mutates product state.
Discovery and shell completion
Interactive terminals can open a searchable command palette with bucky (no
arguments). The palette returns canonical argv for copy/run; it does not execute
mutations. Non-interactive stdout prints five starter examples.
bucky help shows bounded contextual suggestions based on your
profile, authentication, readiness, recent projects, and recent conversations.
Each probe is read-only, timed out, and labeled when unavailable. Suggestions
show canonical argv only — they are never executed automatically.
On first interactive run, Bucky walks through profile setup and auth login,
then probes readiness. That flow writes only local auth/profile configuration.
bucky
bucky help
bucky palette
bucky '?' # legacy alias; quote it because ? is a shell glob
bucky chat resume
bucky chat resume <conversation-id>
bucky completion zsh > ~/.zsh/completions/_bucky
bucky completion bash >> ~/.bashrc
bucky completion fish > ~/.config/fish/completions/bucky.fishShell completion uses bounded read-only resolvers for projects, conversations,
reviewed city slugs, and agent check --require tokens. JSON and piped stdout
never open the palette.
Public command reference
Agent-safe inventory (generated from CommandSpec; do not edit by hand):
| Command | Kind | Auth | Summary |
|---|---|---|---|
agent check | read | product | Probe bounded product readiness for agent workflows |
agent-context | read-local | none | Emit the versioned agent-safe command introspection document |
analysis run | write | product | Enqueue a fresh project analysis run |
analysis show | read | product | Show current project analysis and agentStatus |
analysis wait | read | product | Poll agentStatus until analysis is current, failed, or none |
auth login | write-local | none | Sign in and persist a profile session |
auth logout | write-local | none | Remove stored credentials for the active profile |
auth status | read-local | none | Show profile, token source, and expiry without a network call |
auth whoami | read | product | Show the authenticated user subject and email |
capabilities | read-local | none | Show this CLI build command and transport contract |
chat resume | read | product | Select a recent conversation and show the canonical continuation argv |
chat turn | write | product | Send one project-scoped chat turn (supports --dry-run) |
city ingest | write | ops-local | Run reviewed city knowledge ingest (supports --dry-run) |
city next | read | ops-local | Show the next onboarding action for a municipality |
city status | read | ops-local | Show municipality onboarding status from geo scripts |
completion bash | read-local | none | Emit a bash completion script |
completion fish | read-local | none | Emit a fish completion script |
completion zsh | read-local | none | Emit a zsh completion script |
conversations get | read | product | Load one conversation with messages |
conversations list | read | product | List conversations for a project |
doctor | read | none | Check local CLI configuration and connectivity |
documents list | read | product | List project documents (metadata only) |
evidence list | read | product | List project evidence substrate records |
help | read-local | none | Show bounded contextual suggestions for your profile and state |
knowledge search | read | product | Search zoning and product knowledge |
operations list | read-local | none | List secret-free mutation receipts for the active profile |
operations show | read-local | none | Show one mutation receipt by id |
parcels search | read | product | List parcels near a point for land assembly |
programs list | read | product | List development programs for a project |
projects archive | write | product | Soft-cancel a project (supports --dry-run) |
projects attach-parcels | write | product | Attach additional parcels to an existing project (supports --dry-run) |
projects create | write | product | Create a project (supports --dry-run) |
projects create-assembly | write | product | Create a multi-parcel land assembly project (supports --dry-run) |
projects get | read | product | Get one project by id |
projects list | read | product | List accessible projects with bounded pagination |
projects update | write | product | Update project fields (supports --dry-run) |
references add | write | product | Attach a knowledge section to a project (supports --dry-run) |
references list | read | product | List knowledge references attached to a project |
reports compose | read | product | Compose a grounded report plan from project analysis |
reports export | write | product | Export a report PDF to a local file (spends records.exports) |
undo | write | product | Undo a reversible mutation from its receipt |
zoning show | read | product | Show per-parcel zoning, built-form overlay and site envelope |
Example invocations:
pnpm bucky -- agent-context
pnpm bucky -- capabilities
pnpm bucky -- help
pnpm bucky -- doctor
pnpm bucky -- completion zsh
pnpm bucky -- completion bash
pnpm bucky -- completion fish
pnpm bucky -- auth login
pnpm bucky -- auth status
pnpm bucky -- auth whoami
pnpm bucky -- auth logout
pnpm bucky -- agent checkProjects:
pnpm bucky -- projects list --limit 20
pnpm bucky -- projects get <project-id>
pnpm bucky -- projects create --name "Main Street" --address "12 Main St" --dry-run
pnpm bucky -- projects update <project-id> --name "Main Street Infill" --dry-run
pnpm bucky -- projects archive <project-id> --dry-runprojects archive is a soft cancel: it retains the project row.
Land assembly (multi-parcel projects)
projects create makes a single-location project: it writes the project and its location,
but attaches no parcels. For a site made of several parcels — a campus, a block assembly,
a building plus its parking lot — use projects create-assembly.
pnpm bucky -- parcels search --lat 45.004744 --lng -93.261962 --radius 120
pnpm bucky -- projects create-assembly --name "Holy Cross Campus" \
--lat 45.004744 --lng -93.261962 --radius 120 \
--parcel 1402924210178 --parcel 1402924210122 --dry-run
pnpm bucky -- projects attach-parcels <project-id> \
--lat 45.004744 --lng -93.261962 --parcel 1402924220152 --role context --dry-runThe usual flow is parcels search to find external ids near a point, then create-assembly
with the ids you want. Every parcel is attached with role build; use
attach-parcels --role context afterwards for surrounding parcels you want as context
rather than as part of the site.
Two modes. With --lat/--lng, the CLI looks the parcels up and derives the commit
polygon from their own geometry — so even --dry-run performs that lookup and needs auth.
With --input, you supply geoDivisionId, polygon and parcelExternalIds yourself;
that mode is fully offline and is the only way to commit a non-rectangular polygon.
Parcel order matters. The first --parcel becomes the seed lot: it anchors the
project's location and parcel ordering. Repeat the flag or pass a comma-separated list;
duplicates are dropped without reordering.
create-assembly is not server-idempotent. Unlike projects create, the assembly
endpoint inserts unconditionally — a resend creates a second project. The CLI disables
transport retries for this command and offers no --retry-operation. If a run ends with
an unknown outcome, run projects list and archive any duplicate rather than retrying.
bucky undo <receipt-id> reverses a completed assembly.
parcels search returns no owner names — the API strips ownership from area
candidates. Pass --full to include each parcel's boundary geometry.
Conversations and chat:
pnpm bucky -- conversations list --project <project-id> --limit 20
pnpm bucky -- conversations get <conversation-id> --project <project-id>
pnpm bucky -- chat resume
pnpm bucky -- chat resume <conversation-id>
pnpm bucky -- chat turn --project <project-id> --message "Summarize this site" --dry-run
pnpm bucky -- chat turn --project <project-id> --conversation <conversation-id> \
--message "Continue with the permit risks"Pass the opaque nextCursor returned by conversations list back through
--cursor. chat resume selects a recent conversation and prints the canonical
chat turn --conversation <id> argv. Sending still requires an explicit
--message and mutation review.
Knowledge and references:
pnpm bucky -- knowledge search --q "front setback" --limit 10
pnpm bucky -- references list <project-id> --limit 20 --offset 0
pnpm bucky -- references add <project-id> --section <section-uuid> --dry-runCity operations
City commands run only inside a Bucky checkout. They reuse the existing
pnpm geo:* entrypoints and read ops credentials from
apps/bucky-ui/.env.local or the repository .env.local; the service-role key
is never copied into XDG configuration.
pnpm bucky -- city status --city us-il-chicago
pnpm bucky -- city next --city us-il-chicago
pnpm bucky -- city ingest --city us-il-chicago --dry-runThe existing pnpm geo:* commands remain supported for detailed operator
workflows and troubleshooting.
Last updated on