Command-Line Interface

The @agentkitai/agentgate-cli package provides a command-line interface for managing approval requests.

Installation

# Global install
npm install -g @agentkitai/agentgate-cli

# Or run with npx
npx @agentkitai/agentgate-cli --help

# Or from the monorepo
pnpm --filter @agentkitai/agentgate-cli build

Configuration

Using Environment Variables

export AGENTGATE_URL=http://localhost:3000
export AGENTGATE_API_KEY=agk_your_api_key

Using the Config Command

# Set server URL
agentgate config set serverUrl http://localhost:3000

# Set API key
agentgate config set apiKey agk_your_api_key

# View current config
agentgate config show

Configuration is stored in ~/.agentgate/config.json.

Commands

agentgate request <action>

Create a new approval request.

agentgate request send_email \
  --params '{"to": "user@example.com", "subject": "Hello"}' \
  --urgency high \
  --context '{"agent": "email-bot"}'

Options:

Option	Description
--params, -p	JSON parameters for the action
--urgency, -u	Urgency level: low, normal, high, critical
--context, -c	Additional context (JSON)
--json	Output as JSON

agentgate status <id>

Get the status of a request.

agentgate status req_abc123

Output:

Request: req_abc123
Action:  send_email
Status:  pending
Urgency: high
Created: 2024-01-15T10:30:00Z

agentgate list

List approval requests.

# List pending requests
agentgate list --status pending

# List all with limit
agentgate list --limit 20

# Filter by action
agentgate list --action send_email

# Output as JSON
agentgate list --json

Options:

Option	Description
--status, -s	Filter by status
--action, -a	Filter by action type
--limit, -l	Maximum results (default: 10)
--offset, -o	Pagination offset
--json	Output as JSON

agentgate approve <id>

Approve a pending request.

agentgate approve req_abc123 --reason "Looks good to me"

Options:

Option	Description
--reason, -r	Reason for approval

agentgate deny <id>

Deny a pending request.

agentgate deny req_abc123 --reason "Not authorized for this action"

Options:

Option	Description
--reason, -r	Reason for denial

agentgate override

Manage per-agent tool override guardrails (issue #14). An override gates a tool for a specific verified agent: require_approval escalates the call to the human approval flow, while deny hard-blocks it (the MCP tool call returns a synchronous error and never runs). When several overrides match, deny wins.

# Hard-deny an agent from any "fs.*" tool for the next hour
agentgate override create --agent agt_abc --tool 'fs.*' --action deny --ttl 3600 --reason "incident #42"

# Escalate deploys to human approval (default action)
agentgate override create --agent agt_abc --tool deploy_production

agentgate override list
agentgate override rm ovr_abc123

create options:

Option	Description
--agent, -a	Verified agent id (required)
--tool, -t	Tool name or glob pattern, e.g. fs.* (required)
--action	require_approval (default) or deny
--reason, -r	Why the override exists
--ttl	Expire after N seconds (default: no expiry)

agentgate config

Manage CLI configuration.

# Show current configuration
agentgate config show

# Set a value
agentgate config set serverUrl http://localhost:3000
agentgate config set apiKey agk_...

# Clear configuration
agentgate config clear

Examples

Create and Wait for Decision

# Create request and capture ID
REQUEST_ID=$(agentgate request deploy_production \
  --params '{"version": "1.2.3"}' \
  --urgency high \
  --json | jq -r '.id')

echo "Created request: $REQUEST_ID"

# Poll for decision
while true; do
  STATUS=$(agentgate status $REQUEST_ID --json | jq -r '.status')
  if [ "$STATUS" != "pending" ]; then
    echo "Decision: $STATUS"
    break
  fi
  sleep 5
done

Batch Approve

# Approve all pending requests for a specific action
agentgate list --status pending --action notify_user --json | \
  jq -r '.[].id' | \
  xargs -I {} agentgate approve {} --reason "Batch approved"

Integration with Scripts

#!/bin/bash

# Request approval before deployment
RESULT=$(agentgate request deploy \
  --params "{\"env\": \"production\", \"sha\": \"$GIT_SHA\"}" \
  --urgency high \
  --json)

REQUEST_ID=$(echo $RESULT | jq -r '.id')

echo "Waiting for approval: $REQUEST_ID"
echo "Dashboard: http://localhost:5173/requests/$REQUEST_ID"

# Wait up to 10 minutes
for i in {1..120}; do
  STATUS=$(agentgate status $REQUEST_ID --json | jq -r '.status')
  
  case $STATUS in
    approved)
      echo "✅ Approved! Deploying..."
      ./deploy.sh
      exit 0
      ;;
    denied)
      echo "❌ Denied. Aborting deployment."
      exit 1
      ;;
    expired)
      echo "⏰ Request expired. Aborting."
      exit 1
      ;;
  esac
  
  sleep 5
done

echo "Timeout waiting for approval"
exit 1

JSON Output

All commands support --json for machine-readable output:

# Get JSON output
agentgate list --json

# Parse with jq
agentgate list --json | jq '.[] | select(.urgency == "critical")'