sentryagent-idp/openspec/changes/archive/2026-04-02-phase-4-developer-growth/specs/cli-tool/spec.md

ADDED Requirements

Requirement: sentryagent CLI is an installable npm package

The system SHALL provide a sentryagent CLI at cli/ with its own package.json, built with commander and chalk, and published to npm as sentryagent. The CLI SHALL be installable globally via npm install -g sentryagent. The CLI binary SHALL be named sentryagent.

Scenario: CLI installs and shows help

• WHEN a user runs npm install -g sentryagent and then sentryagent --help
• THEN the command displays available subcommands and global options without errors

Scenario: CLI version flag works

• WHEN a user runs sentryagent --version
• THEN the CLI outputs its version number matching package.json

Requirement: CLI persists configuration in ~/.sentryagent/config.json

The CLI SHALL store API endpoint (apiUrl) and credentials (clientId, clientSecret) in ~/.sentryagent/config.json. The sentryagent configure command SHALL prompt for these values interactively and write them to the config file. All other commands SHALL read from this config file automatically.

Scenario: Configure command saves credentials

• WHEN a user runs sentryagent configure and enters an API URL, client ID, and client secret
• THEN ~/.sentryagent/config.json is created or updated with the entered values

Scenario: Command fails gracefully when not configured

• WHEN a user runs any command before running sentryagent configure
• THEN the CLI outputs a human-readable error: "Not configured. Run sentryagent configure first."

Requirement: register-agent command registers a new agent

The CLI SHALL provide sentryagent register-agent --name <name> [--description <desc>] that calls POST /agents and outputs the created agent's ID and name.

Scenario: Agent registered successfully

• WHEN a user runs sentryagent register-agent --name "my-agent"
• THEN the CLI outputs the new agent ID and confirms registration

Requirement: list-agents command lists all agents

The CLI SHALL provide sentryagent list-agents that calls GET /agents and outputs a formatted table of agent ID, name, status, and creation date.

Scenario: Agents listed in table format

• WHEN a user runs sentryagent list-agents
• THEN the CLI outputs a formatted table with all agents for the authenticated tenant

Requirement: issue-token command issues an OAuth2 token

The CLI SHALL provide sentryagent issue-token --agent-id <id> that calls POST /oauth2/token and outputs the access token and expiry.

Scenario: Token issued successfully

• WHEN a user runs sentryagent issue-token --agent-id <id>
• THEN the CLI outputs the access token and its expiry timestamp

Requirement: rotate-credentials command rotates agent credentials

The CLI SHALL provide sentryagent rotate-credentials --agent-id <id> that calls POST /agents/:id/credentials/rotate and outputs the new client secret.

Scenario: Credentials rotated with confirmation prompt

• WHEN a user runs sentryagent rotate-credentials --agent-id <id>
• THEN the CLI prompts for confirmation ("This will invalidate the current secret. Continue? [y/N]") before rotating

Requirement: tail-audit-log command polls and streams audit events

The CLI SHALL provide sentryagent tail-audit-log [--agent-id <id>] that polls GET /audit/logs every 5 seconds and streams new events to stdout in a human-readable format. The command SHALL run until the user presses Ctrl+C.

Scenario: Audit log events stream to stdout

• WHEN a user runs sentryagent tail-audit-log
• THEN new audit events appear in the terminal as they are created, one per line

Requirement: CLI supports bash and zsh shell completion

The CLI SHALL provide sentryagent completion bash and sentryagent completion zsh commands that output shell completion scripts. Installation instructions SHALL be included in the CLI README.

Scenario: Bash completion script is generated

• WHEN a user runs sentryagent completion bash
• THEN a valid bash completion script is output to stdout