sentryagent-idp/cli/README.md

# sentryagent CLI

The official command-line interface for [SentryAgent.ai](https://sentryagent.ai) — manage agents, issue OAuth2 tokens, rotate credentials, and stream audit logs from your terminal.

---

## Installation

### From npm (once published)

```bash
npm install -g sentryagent
```

### From source

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

---

## Configuration

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

```bash
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.

```bash
sentryagent --version
# 1.0.0
```

### `sentryagent --help` / `-h`

Show all available commands and global options.

```bash
sentryagent --help
```

---

### `sentryagent configure`

Interactively configure the CLI.

```bash
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.

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

**Options:**

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

**Example:**

```bash
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.

```bash
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.

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

**Options:**

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

**Example:**

```bash
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.

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

**Options:**

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

**Example:**

```bash
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.

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

**Options:**

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

**Example (all events):**

```bash
sentryagent tail-audit-log
```

**Example (filtered by agent):**

```bash
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

```bash
sentryagent completion bash
```

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

```bash
source <(sentryagent completion bash)
```

Or write to a file:

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

#### Zsh

```bash
sentryagent completion zsh
```

To enable permanently, add to `~/.zshrc`:

```bash
source <(sentryagent completion zsh)
```

Or write to a file in your `$fpath`:

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

---

## Shell Completion Setup

### Bash (one-time setup)

```bash
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)

```bash
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`:

```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)