Safety & permissions
When an AI agent operates the CLI on your behalf, every command has real consequences — creating products, refunding buyers, deleting discounts. The AI Toolkit is designed so an agent stays inside guardrails you control.
The safety protocol
The foundation skill shoplazza-common sets this protocol for destructive (cancel, delete), batch, and money-moving writes such as refunds and charges:
- Preview — run the command with
--dry-run, which prints the request without sending it. - Restate — summarize what the operation will change.
- Confirm — wait for your explicit confirmation before executing.
Other writes, such as creating a product or discount with a + shortcut, run directly once the required values are confirmed. Read-only commands (+search, +count, list, get) run without confirmation.
/shoplazza-orders Refund 15.50 to the buyer on order 660011
The agent previews the refund with --dry-run, restates the amount and restock behavior, and waits for your "yes" before running it for real.
At an interactive terminal the CLI itself also asks a human to confirm destructive commands: orders +refund has you retype the order ID, while products +unpublish, every delete / cancel command, and auth logout ask to proceed. Agents, pipes, CI, and --dry-run never see these prompts, so in an agent session the protocol above is what guards each write.
Scopes limit what an agent can do
Authentication is scoped per domain. An agent can only touch domains you granted at login:
shoplazza auth login --store-domain my-store.myshoplaza.com --domain products,orders
The command above lets the agent manage products and orders — but not customers, discounts, or shop settings. To grant fine-grained OAuth scopes instead:
shoplazza auth login --store-domain my-store.myshoplaza.com --scope read_product,read_order
Granting only read_* scopes gives an agent a read-only view of a domain. A call outside the granted scopes is rejected with HTTP 403, which the CLI returns as an auth error with a hint to log in again with --domain or --scope. See Authentication → Scope mapping.
Practical guardrails
- Least privilege — grant only the domains and scopes the task needs. A reporting agent needs
read_*only. - Review before run — keep the confirm step on for writes; read the restated command before approving.
- Credentials are encrypted at rest — tokens are stored AES-256-GCM-encrypted in the CLI's config directory, never as plain text in config files.
- Separate stores — point agents at a development store first; switch with
shoplazza auth store use. - CI secrets — in automated runs, pass a UAT as an encrypted secret, never in the prompt or source. See Headless & CI.