feat(phase-4): WS2 + WS3 — Developer Portal (Next.js 14) and CLI tool (sentryagent)
WS2: Developer Portal (portal/) - Standalone Next.js 14 + Tailwind CSS app — independent deployment - Home page: hero, feature grid, CTA to /get-started - /pricing: free tier limits table (10 agents, 1k calls/day) + paid tier CTA - /sdks: all 4 SDKs (Node.js, Python, Go, Java) with install + code examples - /api-explorer: Swagger UI from NEXT_PUBLIC_API_URL/openapi.json, persistAuthorization - /get-started: 4-step wizard (setup → register agent → credentials → SDK snippet) - Shared Nav component with active-link highlighting - Build: 8/8 static pages, zero TypeScript errors WS3: CLI Tool (cli/ — npm package: sentryagent) - configure, register-agent, list-agents, issue-token, rotate-credentials, tail-audit-log - Auto OAuth2 token fetch + 30s-buffer cache via client_credentials flow - chalk-formatted table output, confirmation prompts, bounded audit log dedup - bash + zsh shell completion scripts - README with installation, all commands, and completion setup - Build: tsc clean, node dist/index.js --help verified Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
SentryAgent.ai Developer
348
cli/README.md
Normal file
348
cli/README.md
Normal file
@@ -0,0 +1,348 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user