Command line

Write safety

Write commands are cautious by default. The CLI previews the change first, requires an explicit submit, and requires a stable idempotency key so retried jobs do not apply the same change twice.

Preview first

A write call without --yes runs as a preview. Nothing changes in Amazon. The result shows counts, validation feedback, and warnings so you can inspect what would happen before submitting.

# preview by default — no change is submitted
agentcentral tools call update_keyword_bids --input bids.json --format json

Submit with --yes and an idempotency key

--yes tells the CLI to submit the change. Every submit also needs --idempotency-key: a stable run identifier such as bid-sync-2026-05-31. If you submit without one, the CLI exits before sending the request.

# submit — requires --yes and a stable idempotency key
agentcentral tools call update_keyword_bids   --input bids.json --yes --idempotency-key "bid-sync-2026-05-31"   --format json

The same key makes retries safe

If a job times out and you rerun it with the same idempotency key, agentcentral recognizes the prior submission and does not apply a second write. For scheduled jobs, derive the key from the job name and run date.

Understand the result

Write tools return a consistent summary with the requested, applied, failed, and previewed counts:

{
  "mode": "submit",
  "status": "accepted",
  "requested_count": 12,
  "accepted_count": 12,
  "failed_count": 0,
  "previewed_count": 0,
  "idempotency_key": "bid-sync-2026-05-31",
  "rows": [],
  "warnings": []
}

Status to exit code

The CLI maps write statuses into shell exit codes so automation can branch safely:

Status	Exit	Meaning
`preview`	0	Preview completed; no write was made
`accepted`	0	Write was accepted
`duplicate_blocked`	0	This idempotency key was already submitted; the prior result stands and no new write was made
`validation_error`	5	Input validation failed
`blocked`	7	agentcentral blocked the write for safety or scope reasons
`partial`	9	Some rows succeeded and some failed; inspect the returned counts and row details

Local read-only mode

--read-only hides write tools and rejects write calls in the CLI or bridge before they leave your machine. Treat it as a convenience filter, not a security boundary. For a real read-only boundary, create a read-only key in the dashboard. See security.