sentryagent-idp/cli/README.md

sentryagent CLI

The official command-line interface for SentryAgent.ai — manage agents, issue OAuth2 tokens, rotate credentials, and stream audit logs from your terminal.

---

Installation

From npm (once published)

npm install -g sentryagent

From source

cd cli/
npm install
npm run build
npm install -g .

---

Configuration

Before using any command, configure the CLI with your API endpoint and credentials:

sentryagent configure

You will be prompted for:

Field	Description
API URL	The SentryAgent.ai API base URL (e.g. https://api.sentryagent.ai)
Client ID	Your tenant client ID
Client Secret	Your tenant client secret

Configuration is stored at ~/.sentryagent/config.json with permissions 0600.

If any command is run before sentryagent configure has been called, the CLI exits with:

Not configured. Run `sentryagent configure` first.

---

Commands

sentryagent --version / -v

Output the installed CLI version.

sentryagent --version
# 1.0.0

sentryagent --help / -h

Show all available commands and global options.

sentryagent --help

---

sentryagent configure

Interactively configure the CLI.

sentryagent configure

Prompts:

SentryAgent CLI Configuration
────────────────────────────────────────
API URL (e.g. https://api.sentryagent.ai): https://api.sentryagent.ai
Client ID: tenant_01ABC...
Client Secret: ****

✓ Configuration saved to ~/.sentryagent/config.json

---

sentryagent register-agent

Register a new agent with the identity provider.

sentryagent register-agent --name <name> [--description <desc>]

Options:

Flag	Required	Description
--name <name>	Yes	Agent display name
--description	No	Agent description

Example:

sentryagent register-agent --name "billing-agent" --description "Handles billing workflows"

Output:

✓ Agent registered successfully

Agent ID:    01ARZ3NDEKTSV4RRFFQ69G5FAV
Name:        billing-agent
Description: Handles billing workflows
Status:      active

---

sentryagent list-agents

List all agents registered for your tenant, displayed as a formatted table.

sentryagent list-agents

Output:

AGENT ID                    NAME                      STATUS      CREATED AT
────────────────────────────────────────────────────────────────────────────
01ARZ3NDEKTSV4RRFFQ69G5FAV  billing-agent             active      4/2/2026, 9:00:00 AM
01ARZ3NDEKTSV4RRFFQ69G5FAX  auth-agent                active      4/1/2026, 3:00:00 PM
────────────────────────────────────────────────────────────────────────────
Total: 2

---

sentryagent issue-token

Issue an OAuth2 client_credentials access token for a specific agent.

sentryagent issue-token --agent-id <id>

Options:

Flag	Required	Description
--agent-id <id>	Yes	Target agent ID

Example:

sentryagent issue-token --agent-id 01ARZ3NDEKTSV4RRFFQ69G5FAV

Output:

✓ Token issued successfully

Access Token:
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Token Type:  Bearer
Expires In:  3600s
Expires At:  2026-04-02T10:00:00.000Z

---

sentryagent rotate-credentials

Rotate the client secret for an agent. Prompts for confirmation before proceeding.

sentryagent rotate-credentials --agent-id <id>

Options:

Flag	Required	Description
--agent-id <id>	Yes	Target agent ID

Example:

sentryagent rotate-credentials --agent-id 01ARZ3NDEKTSV4RRFFQ69G5FAV

Output:

⚠  This will invalidate the current secret for agent 01ARZ3NDEKTSV4RRFFQ69G5FAV
This will invalidate the current secret. Continue? [y/N] y

✓ Credentials rotated successfully

Client ID:     01ARZ3NDEKTSV4RRFFQ69G5FAV
Client Secret: cs_new_secret_value_here

Store the new client secret securely — it will not be shown again.

---

sentryagent tail-audit-log

Poll the audit log API every 5 seconds and stream new events to stdout. Press Ctrl+C to stop.

sentryagent tail-audit-log [--agent-id <id>]

Options:

Flag	Required	Description
--agent-id <id>	No	Filter events for a specific agent

Example (all events):

sentryagent tail-audit-log

Example (filtered by agent):

sentryagent tail-audit-log --agent-id 01ARZ3NDEKTSV4RRFFQ69G5FAV

Output:

Tailing audit log — press Ctrl+C to stop
────────────────────────────────────────────────────────────
4/2/2026, 9:05:00 AM  agent.token.issued  outcome=success  agent=01ARZ3NDEKTSV...  id=evt_01...
4/2/2026, 9:10:03 AM  agent.registered    outcome=success  id=evt_02...
^C

Stopped.

---

sentryagent completion

Output shell completion scripts.

Bash

sentryagent completion bash

To enable permanently, add to ~/.bashrc or ~/.bash_profile:

source <(sentryagent completion bash)

Or write to a file:

sentryagent completion bash > ~/.bash_completion.d/sentryagent

Zsh

sentryagent completion zsh

To enable permanently, add to ~/.zshrc:

source <(sentryagent completion zsh)

Or write to a file in your $fpath:

sentryagent completion zsh > ~/.zsh/completions/_sentryagent

---

Shell Completion Setup

Bash (one-time setup)

mkdir -p ~/.bash_completion.d
sentryagent completion bash > ~/.bash_completion.d/sentryagent
echo 'source ~/.bash_completion.d/sentryagent' >> ~/.bashrc
source ~/.bashrc

Zsh (one-time setup)

mkdir -p ~/.zsh/completions
sentryagent completion zsh > ~/.zsh/completions/_sentryagent
echo 'fpath=(~/.zsh/completions $fpath)' >> ~/.zshrc
echo 'autoload -Uz compinit && compinit' >> ~/.zshrc
source ~/.zshrc

After setup, pressing Tab after sentryagent will autocomplete commands and flags.

---

Configuration File

The config file is stored at ~/.sentryagent/config.json:

{
  "apiUrl": "https://api.sentryagent.ai",
  "clientId": "tenant_01ABC...",
  "clientSecret": "cs_secret_value"
}

The directory is created with mode 0700 and the file with mode 0600 to prevent other users from reading your credentials.

---

Environment

• Node.js >= 18.0.0 is required (uses the built-in fetch API)
• All HTTP requests use OAuth2 client_credentials tokens fetched automatically from your configuration
• Tokens are cached in memory for the duration of the CLI session (refreshed 30 seconds before expiry)