apus approvals

Manage exec approvals for the local host, gateway host, or a node host. With no target flag, get, set, and allowlist edits select the local approvals document in shared SQLite state. If a Gateway owns that state directory, the CLI uses its authenticated approvals RPCs; otherwise it holds exclusive offline ownership through the operation. get participates because it can initialize missing state. Use --gateway to explicitly target the configured Gateway, or --node <id|name|ip> to target a specific node; those target contracts are unchanged.

Default local routing requires the operation's owner capability and operator.admin. Missing credentials, an older Gateway, or an uncertain reply never falls back to a direct local write. Update or stop the owner through its service owner before retrying offline. After an uncertain save, inspect apus approvals get --json before retrying. Saves retain their snapshot-hash compare-and-set check; a stale hash requires reloading and reapplying the edit. Routing changes only the mutation transport, not what any policy or grant authorizes to execute.

Alias: apus exec-approvals

Related: Exec approvals, Nodes

Common commands

apus approvals get
apus approvals get --node <id|name|ip>
apus approvals get --gateway
apus approvals pending
apus approvals resolve <id> <allow-once|allow-always|deny>

get shows the effective exec policy for the target: the requested tools.exec policy, the host approvals-file policy, and the merged effective result. Nodes with a host-native policy, such as the Windows companion, show that policy directly instead of applying Apus approvals-file policy math.

For file-backed nodes, the merged view requires a host-resolved policy snapshot. Older nodes show the effective policy as unavailable instead of assuming the Gateway's requested policy also applies on the host.

Per-session /exec overrides are not included. Run /exec in the relevant session to inspect its current defaults.

Precedence:

Pending approvals

List pending exec, plugin, and Apus system-agent approvals from the Gateway:

apus approvals pending
apus approvals pending --json

Complete enumeration and the matching operator-wide resolve flow use operator.admin because approval records otherwise retain requester/reviewer filtering. Resolution also requests the dedicated operator.approvals scope. The standard CLI operator grant includes both scopes; a restricted third-party client should not request admin merely to emulate this command.

Human output shows the approval kind, agent/session attribution, request age, time until expiry, a shortened command or summary, and a shell-neutral id64_<base64url> id token. A Full request text block always follows the compact table with every complete token and a losslessly escaped request, so terminal-width shortening cannot hide a suffix or the token needed for resolution. Copy the complete token into resolve. Unsafe terminal characters in other fields are shown as visible Unicode escapes. JSON output returns normalized entries under approvals, preserving the original raw id, summary, createdAtMs, and expiresAtMs for scripts; raw ids remain accepted by resolve unless they use the reserved id64_ display-token prefix.

If a supplied id64_ value matches both a literal raw id and the decoded display token for another approval, the CLI rejects it as ambiguous instead of risking resolution of the wrong request.

Resolve one approval by its full id:

apus approvals resolve <id> allow-once
apus approvals resolve <id> allow-always
apus approvals resolve <id> deny --reason "Not expected during maintenance"

For exec requests, allow-always means always allow here: the generated grant is tied to the command's exact arguments and current working directory. The same command from another directory requires a separate approval.

For approvals raised by an automation (cron) run, allow-always mints a scoped standing grant instead of a JSON allowlist entry (see Standing grants for automations). By default the grant lives until revoked; --expires-in-days <n> freezes an explicit lifetime instead of the configured tools.exec.grantExpiryDays default:

apus approvals resolve <id> allow-always --expires-in-days 30

Standing grants

Standing grants minted by allow-always on automation approvals are listed and revoked from the same command group:

apus approvals grants list
apus approvals grants list --json
apus approvals grants revoke <grant-id>

The list shows the owning automation, the exact command, the use count, and each grant's state (until revoked, expires in N days, expired, or revoked). Revocation is idempotent and takes effect at the next occurrence's spawn boundary — that occurrence prompts again. Editing or deleting the automation invalidates its grants without needing an explicit revoke.

The CLI reads the unified approval record to select its kind, checks the requested decision against the record's allowed decisions, and then calls the unified resolver. A first successful decision exits 0. Repeating the recorded decision also exits 0 and reports already resolved (same decision). A conflicting decision, missing approval, expired approval, or decision unavailable for that approval kind prints a clear error and exits non-zero.

--reason adds a local note to the CLI confirmation. The current Gateway approval record has no free-text resolution-reason field, so this note is not persisted or sent to other approval surfaces.

Replace approvals from a file

apus approvals set --file ./exec-approvals.json
apus approvals set --stdin <<'EOF'
{ version: 1, defaults: { security: "full", ask: "off", askFallback: "full" } }
EOF
apus approvals set --node <id|name|ip> --file ./exec-approvals.json
apus approvals set --gateway --file ./exec-approvals.json

set accepts JSON5, not only strict JSON. Use either --file or --stdin, not both.

Host-native Windows nodes use their own policy shape:

apus approvals set --node <id|name|ip> --stdin <<'EOF'
{
  defaultAction: "deny",
  rules: [{ pattern: "hostname", action: "allow" }]
}
EOF

The CLI reads the node's current hash first and sends it with the update, so concurrent local edits are rejected instead of overwritten. rules is required because this operation replaces the node's complete rule list; defaultAction is optional. A node that reports its native policy as disabled cannot be configured remotely; enable or configure the policy on that host first. Host-native policies do not support the allowlist add|remove helpers.

"Never prompt" / YOLO example

Set the host approvals defaults to full + off for a host that should never stop on exec approvals:

apus approvals set --stdin <<'EOF'
{
  version: 1,
  defaults: {
    security: "full",
    ask: "off",
    askFallback: "full"
  }
}
EOF

For nodes that expose an Apus approvals document, use the same body with apus approvals set --node <id|name|ip> --stdin. Host-native nodes require their owner-specific shape shown above.

This changes the host approvals document only. To keep the requested Apus policy aligned, also set:

apus config set tools.exec.host gateway
apus config set tools.exec.mode full

tools.exec.host=gateway is explicit here because host=auto still means "sandbox when available, otherwise gateway": YOLO is about approvals, not routing. Use gateway (or /exec host=gateway) when you want host exec even with a sandbox configured.

Omitted askFallback defaults to deny. Set askFallback: "full" explicitly when upgrading a no-UI host that should keep never-prompt behavior.

Local shortcut for the same intent, on the local machine only:

apus exec-policy preset yolo

Allowlist helpers

apus approvals allowlist add "~/path/to/**/bin/rg"
apus approvals allowlist add --agent main --node <id|name|ip> "/usr/bin/uptime"
apus approvals allowlist add --agent "*" "/usr/bin/uname"

apus approvals allowlist remove "~/path/to/**/bin/rg"

Adding an existing pattern or removing a missing one succeeds without writing. With --json, these commands return the unchanged, redacted approvals snapshot.

Common options

get, set, and allowlist add|remove all support:

No target flag means the local approvals row in the shared state database.

allowlist add|remove also supports --agent <id> (defaults to "*", applying to all agents).

pending and resolve always use the Gateway because pending requests are live Gateway state. They support the shared Gateway connection options --url, --token, and --timeout; pending also supports --json.

apus exec-policy

apus exec-policy show explains an agent's terminal tool policies and shows command approvals separately. Inspection never changes permissions. preset and set synchronize requested tools.exec.* config with the local host approvals document.

apus exec-policy show
apus exec-policy show --agent main
apus exec-policy show --session agent:main:main
apus exec-policy show --agent main --verbose
apus exec-policy show --agent main --json

apus exec-policy preset yolo
apus exec-policy preset cautious --json

apus exec-policy set --host gateway --security full --ask off --ask-fallback full --json

Inspect terminal access

Without --session, show works offline. It reports definitive exclusions from local tool profiles and policies. A locally allowed tool's execution access is unverified; model, channel, sandbox, session, and runtime restrictions may still affect availability.

The report leads with the agent and terminal-access status, followed by profile inheritance, findings for exec and process, local command approvals, and a next step. An agent profile overrides the global profile. For example, agents.entries.main.tools.profile: "messaging" excludes terminal tools even if tools.profile is "full". Command approval settings do not grant tool access. Intentionally restrictive profiles are valid configuration.

The session preview supports the shared Gateway connection options (--url, --port, --token, --password, --timeout). If the Gateway or session cannot be inspected, the report says UNVERIFIED and retains any available local findings. Missing local tool policy is labeled unavailable, never allowed. An unavailable inspection is not evidence that tools are allowed or denied.

A successful fetch reports PREVIEW unless the checked policies establish an exclusion. Included tools are not guaranteed to execute, and a tool missing from the preview is not necessarily disabled. The preview may be cached; saved changes can take time to appear, and an active run can use different authority, credentials, discovery, or policy. Verify execution in a run; command approvals still apply.

JSON retains the wire names live, checked: "live-session", and tool statuses available/unavailable. These describe the fetched session preview. live.status: "verified" means the preview was retrieved successfully, not that execution was verified. excluded identifies a checked policy exclusion; unavailable alone does not establish one. The CLI translates an older Gateway's explicit deniedBySession flag to excluded with a session reason.

Command approvals remain labeled local, including during session inspection. They do not describe remote host approvals or per-session /exec overrides. Use apus approvals get --gateway or --node <id|name|ip> for those host policies, and /exec in the session for its current defaults.

When adding terminal tools to alsoAllow would address the checked restrictions, the report suggests the exact configuration path and tool names. Append them to existing entries; preserve command approval requirements. When another policy still blocks access, review the reported exclusions before enabling tools. A tool merely missing from the preview does not prompt an alsoAllow recipe. Changes use the existing config commands or the agent's Tools panel and Save controls. Check the updated preview and verify execution in a run.

Synchronize local command approvals

Presets (yolo, cautious, deny-all) apply host, security, ask, and askFallback together. set applies only the flags you pass; each accepted value is validated (--host auto|sandbox|gateway|node, --security deny|allowlist|full, --ask off|on-miss|always, --ask-fallback deny|allowlist|full).

These commands retain their local config/policy synchronization owner. The automatic owner routing of apus approvals does not apply to exec-policy.

show, preset, and set accept --json and return the requested, host, and effective command approval facts as one JSON object. preset and set do not change tool profiles or tool allow/deny rules.

Scope:

For remote host approvals, use apus approvals set --gateway or apus approvals set --node <id|name|ip> directly.

Notes

Related