The asg CLI

asg is the command-line tool for managing the Permit MCP Gateway, including the entire HTTP Egress Proxy control plane. Anything you can do in the Proxy section of the dashboard — enable the proxy, manage rules and credentials, mint tokens, run diagnostics — you can do with asg, scripted and CI-friendly.

The CLI is the operator and automation surface. End users who simply delegate access to an agent normally do that through the browser consent flow, not the CLI.

Install

npm install -g @permit-io/agent-security-cli

Verify the install:

asg --help
asg proxy --help

Configure

asg resolves settings in priority order: environment variables, then a config file at ~/.agent-security/, then built-in defaults.

# Point at your gateway and store an admin token (saved with restrictive permissions).
asg config set gateway-url https://gateway.example.com
asg login --token <admin-token>

# Verify the token against the gateway.
asg whoami

You can also supply settings through environment variables, which is the preferred approach in CI:

Variable	Purpose
AGENT_SECURITY_API_KEY	Admin token used to authenticate control-plane commands.
AGENT_SECURITY_GATEWAY_URL	Your gateway's admin URL.
AGENT_SECURITY_SUBDOMAIN	Default host subdomain, so you can omit it from each command.
AGENT_SECURITY_CONSENT_URL	Consent origin used by asg proxy authorize (usually auto-derived).
AGENT_SECURITY_PROXY_TOKEN_FILE	Path to the agent's proxy token file (set by asg proxy env).

Treat the admin token as a high-value secret

Prefer the interactive prompt or AGENT_SECURITY_API_KEY over passing the token as a --token flag — command-line flags are visible to other users on the machine via the process list. The CLI scrubs secret-shaped strings from its own error output, but the process list is outside its control.

Output and exit codes

Every command supports machine-readable output so agents and CI can drive it deterministically:

asg proxy rules list acme --json --quiet

• --json emits structured JSON to stdout.
• --quiet drops decorative output (spinners, hints).
• --yes accepts confirmation prompts non-interactively.

Exit codes are stable:

Code	Meaning
0	Success
1	User error — bad input, missing token, cancelled prompt, or a human-denied approval
2	Server error — gateway unreachable, 5xx, or network failure

The asg proxy command tree

Command	What it does
asg proxy config <host> --enable|--disable	Turn proxy mode on or off for a host.
asg proxy rules list|add|update|delete|reorder	Manage egress rules. See Egress Rules.
asg proxy credentials list|create|update|delete	Manage stored upstream secrets (write-only). See Credentials.
asg proxy connect <provider>	Connect an OAuth provider (github_app, notion, google, atlassian) and store the resulting credential.
asg proxy token create <host> --client-id <id>	Mint a short-lived agent proxy token (--out <file> writes it securely).
asg proxy authorize <client_id>	Run the browser consent flow so a human can delegate access to an agent within a trust ceiling.
asg proxy preset list|apply	Browse and apply preset rule + credential packs for common providers.
asg proxy env <host>	Print the HTTP_PROXY / HTTPS_PROXY / NO_PROXY environment for the current shell.
asg proxy container-config <host>	Emit Docker, Docker Compose, or Kubernetes ConfigMap bootstrap config.
asg proxy ca status|download|rotate|trust-shell	Manage the per-host TLS-interception certificate authority. See Connecting Agents.
asg proxy doctor <host>	Diagnose proxy setup end to end.

Run asg proxy <command> --help for the full flag list of any command.

Passing the host subdomain

Most commands take the host subdomain as a positional argument (e.g. asg proxy config acme). If you've set a default with asg config set subdomain acme (or AGENT_SECURITY_SUBDOMAIN), you can omit it. Commands that already take another positional accept the host as a --subdomain flag instead.

Shell completions

Enable tab-completion for your shell:

asg completion --shell zsh >> ~/.zshrc    # or: --shell bash >> ~/.bashrc

---

What's next

• Egress Rules — the rule model in depth.
• Credentials & Connections — static secrets, OAuth connections, and request signing.
• Connecting Agents — asg proxy env, container-config, and doctor in context.