Skip to main content
Docs

Safe writes

How the Bucky CLI previews, confirms, records, undoes, and retries changes — including batch writes of up to 25 items.

Every command that changes something in Bucky — creating a project, attaching parcels, saving a buy box, exporting a report — follows the same rules. You can preview it, you confirm it, it leaves a receipt, and where possible you can undo it.

Preview with --dry-run

bucky projects update <project-id> --name "Main Street Infill" --dry-run

A dry run prints the request it would send, a field-by-field preview of the change, and whether the change can be undone. Nothing is sent to Bucky.

Confirm

  • In a terminal, the CLI shows the same preview and asks [y/N/edit]. Choose edit to change the input in your editor before sending.
  • Everywhere else (--json, piped output, CI), the CLI won't write unless you pass --yes. Review the --dry-run output first, then run the same command with --yes. Without it you get MUTATION_CONFIRMATION_REQUIRED.
bucky --json notes add <project-id> --body "Need a geotech report" --dry-run
bucky --json notes add <project-id> --body "Need a geotech report" --yes

Receipts

Before the first change reaches Bucky, the CLI writes a receipt on your machine. When the change finishes, it updates the same receipt to completed, failed, cancelled, or unknown. Receipts hold no secrets.

bucky operations list
bucky operations show <receipt-id>

Receipts are kept per profile under ${XDG_STATE_HOME:-~/.local/state}/bucky/.

Undo

bucky undo <receipt-id>
bucky undo --last --yes

Undo applies the inverse recorded on the receipt, for example restoring the previous project name or deleting a buy box you just created. Not every write can be undone: --dry-run tells you, and so does bucky --json agent-context (mutation.reversible). Sending a chat message, exporting a report, and running an opportunity screen cannot be undone from the CLI.

Recovering from an unknown outcome

If the network drops mid-write, the receipt ends as unknown: the change may or may not have happened.

  • projects create, projects duplicate, programs create — re-run with --retry-operation <receipt-id> --yes and the same flags. The CLI reuses the original idempotency key, so Bucky won't create a second copy.
  • Everything else — check before you retry. Each command's recovery hint says how, for example bucky screen list before re-running screen create, or bucky projects list before re-running projects create-assembly.

Sending the same payload twice does not de-duplicate on its own.

Batch writes

Thirty write commands — including projects create, projects update, notes add, references add, financing add, and parcels set-role — accept a JSON array on --input. One run shares one sign-in and connection, and writes one receipt per item plus a summary.

bucky --json notes add --input ./notes.json --dry-run
bucky --json notes add --input ./notes.json --yes
bucky --json notes add --input ./notes.json --continue-on-error --yes

To see which commands batch and which fields each item may set:

bucky --json agent-context | jq '.data.commands | with_entries(select(.value.batch)) | keys'

Limits. Up to 25 items per run, checked before anything is sent.

One run can span projects. Pass <project-id> to apply it to every item, or leave it out and give each item its own projectId. Giving both, with different values, is an error.

[
  { "projectId": "…", "body": "Need a geotech report" },
  { "projectId": "…", "body": "Call the surveyor", "title": "Follow-up" }
]

Failures. Every item is validated first, so a bad row stops the run before anything is written. Items are then written in order, stopping at the first failure unless you pass --continue-on-error. Any failure exits 1 with BATCH_PARTIAL_FAILURE and a per-item breakdown:

{
  "batch": true,
  "total": 3,
  "succeeded": 1,
  "failed": 1,
  "skipped": 1,
  "items": [
    { "index": 0, "status": "succeeded", "receiptId": "…", "resourceId": "…" },
    { "index": 1, "status": "failed", "receiptId": "…", "error": { "code": "HTTP_400" } },
    { "index": 2, "status": "skipped", "reason": "stopped-after-failure" }
  ]
}

Safe re-runs of project imports. In a batch projects create, each item gets its own idempotency key. Set idempotencyKey on each item yourself (for example your own record id) so re-running the same import file never creates duplicates:

[
  {
    "name": "North East False Creek",
    "lat": 49.27,
    "lng": -123.11,
    "idempotencyKey": "crm-3715f18b"
  },
  { "name": "King Street", "idempotencyKey": "crm-0777802a" }
]

Commands where a resend would duplicate work don't batch: projects create-assembly, projects invites create, designs set-primary, chat turn, and documents upload.

Last updated on