Agents and control
Approvals
Approve or deny an agent's request from your phone, your inbox, or Slack and Discord, and see how the agent carries on afterwards.
When your rules say an AI agent must ask first, CLI holds the request, tells you, and waits. You see who asked, why, exactly what would change and what it would cost, then approve or deny with one tap.
How to do it: write the rules under Rules for agents in project settings (for example "ask before deleting anything" or "ask before production changes"). Requests then show up in the bell in the dashboard, in your email or phone notifications, and in Slack or Discord if you connected them, with Approve and Deny buttons.
The agent waits and carries on by itself once you decide.
When your rules say an agent must ask first, CLI holds its request, tells you, and waits for a person to decide. You see who asked, why, exactly what will change and what it costs, then approve or deny with one tap.
When an approval is needed
Approvals come from the rules you write for agents (see /docs/agent-permissions). They apply to members and keys with the agent role. A request needs a person's approval when:
- it's destructive and the project asks before deleting: deleting a service or an environment, restoring a backup over a live database, removing a domain, a member or a cron job;
- it adds more than your hourly limit, such as a bigger plan, more copies, a new database or a template;
- it changes production and the project asks before production changes (other environments don't ask);
- it runs a write query on a database (when the project asks before deleting or before production changes), or a command in a container (when it asks before production changes).
People act on their own authority and never need approval. Agents with a long, clean record can skip spending and production approvals if you trust them; destructive ones always ask.
What the agent gets
The agent's request is refused with 403 APPROVAL_REQUIRED. Nothing has changed yet.
{
"error": {
"code": "APPROVAL_REQUIRED",
"message": "A person needs to approve this first: delete a service (old-api)",
"retry": "after_approval",
"details": {
"approvalId": "apr_3f9c2a71d0b4e8a6",
"status": "pending",
"summary": "delete a service (old-api)",
"approveUrl": "https://clicloud.app/approve/apr_3f9c2a71d0b4e8a6",
"expiresAt": 1794268800000,
"retryWith": { "header": "X-CLI-Approval", "value": "apr_3f9c2a71d0b4e8a6" }
}
}
}The agent tells you what it asked for and gives you the link. If it asks for the same thing again before you decide, CLI reuses the open request rather than sending you another.
Requests expire after 24 hours.
How you hear about it
CLI tells owners and admins on every channel at once:
- an email to owners and admins who sign in by email, with an Approve or deny link;
- the bell in the dashboard and, if you turned them on, browser notifications;
- your alert channels (Slack, Discord, Telegram or a webhook) as an
approval_requestedevent, with the agent's reason in the message; - the inbox in the dashboard, which collects everything waiting for a person with a link straight to it.
Browser and phone notifications for an approval have Approve and Deny buttons. A button opens the approval page with that choice ready; one more tap confirms it (with your passkey, if you have one), so a notification alone never approves anything. A failed deploy's notification has a Roll back button that works the same way.
To see what's waiting:
From your terminal:
cli approvalsAsk your agent:
"Check whether anything is waiting for my approval."
With the API:
GET /v1/projects/:id/approvals?status=pendingThe approval page
Every request has a page made for a phone at /approve/:id. It shows, on one screen:
- who asked: the agent's key name, or the person;
- why: the reason the agent gave in its own words (from
X-CLI-Intent); - what will change: the action and its target, such as "delete a service (old-api)";
- what it costs: what it adds per hour and per month;
- Approve and Deny buttons.
Only owners and admins can decide, and an agent can never approve its own request. The same facts are available from GET /v1/approvals/:id/details.
Approve with a second factor
If you've added an authenticator app or a passkey, approving asks for it. The confirmation lasts 10 minutes, so approving several requests in a row only asks once. See Teams and security.
From your terminal:
cli approve apr_3f9c2a71d0b4e8a6
cli deny apr_3f9c2a71d0b4e8a6With the API:
POST /v1/approvals/:id/approve
POST /v1/approvals/:id/denyHow the agent carries on
The agent checks the request's status, at most every 10 seconds, or waits with the
cli_wait_for_approvaltool:APIGET /v1/approvals/:idWhen the status is
approved, it resends the identical request (same path, query and body) with the approval id in a header:APIDELETE /v1/services/svc_old_api X-CLI-Approval: apr_3f9c2a71d0b4e8a6CLI checks the approval matches that exact request from that same agent, uses it up, and makes the change. It's recorded in the flight recorder with an undo button.
An approval works once. Reusing it, sending it with a different request, or sending it after it expired gets APPROVAL_INVALID; the agent then resends without the header to ask again. If you deny the request, the agent stops and asks you what to do instead.
With the MCP server, the agent calls the same tool again with the same arguments plus approvalId.
Approve from Slack and Discord
Approval requests posted to Slack or Discord can carry Approve, Deny and Open buttons, so you can decide without leaving chat.
Setup
Chat buttons need two things:
The operator of your CLI server sets up a Slack app (with interactivity pointed at
/v1/integrations/slack/interactive) and/or a Discord application (with its interactions endpoint at/v1/integrations/discord/interactions). If they haven't, requests still arrive in chat, as plain messages with a link.A project admin adds an alert channel from that app's webhook:
Terminalcli notify add slack https://hooks.slack.com/services/T000/B000/XXXX
Link your chat account once
The first time you click Approve or Deny, CLI doesn't know which CLI account you are. It replies privately with a link:
- Open the link while signed in to CLI (it's valid for 30 minutes).
- The Link your chat account page ties your Slack or Discord account to your CLI account.
- Go back to chat and click the button again.
You only do this once per chat account. Your links are listed at GET /v1/me/chat-links, and you can remove one with DELETE /v1/me/chat-links.
What you can approve in chat
- Spending requests (over your hourly limit) and production changes can be approved or denied with the buttons. The message updates to say who decided.
- Destructive requests and commands or queries always need the approval page, where a second factor can be asked for. Clicking a button on one replies with the page's link instead.
- Only owners and admins of the project can decide. Anyone else who clicks is told so.
Open takes you to the approval page for any request.