CLI Reference
The agentsec CLI manages configuration, agents, roles, and migrations.
YAML-based Commands
These commands work with agentsec.yaml and are the primary interface for v0.1.
agentsec init
Initialize AgentSec by parsing config and generating per-agent API keys and .env files.
agentsec init [--config agentsec.yaml] [--proxy-url http://localhost:3100] [--output .]| Flag | Default | Description |
|---|---|---|
-c, --config | ./agentsec.yaml | Path to config file |
--proxy-url | http://localhost:3100 | Proxy URL to include in agent .env files |
-o, --output | . | Output directory for generated .env files |
Generates one .env file per agent with AGENTSEC_KEY and AGENTSEC_PROXY_URL, and prints the corresponding AGENTSEC_AGENT_KEY_* env vars to set on the proxy side.
agentsec add
Add a new service/credential to the config file. Runs interactively if --name is omitted.
# Interactive
agentsec add
# Non-interactive
agentsec add --name slack --description "Slack API" --auth api-key --api-base https://slack.com/api| Flag | Default | Description |
|---|---|---|
-c, --config | ./agentsec.yaml | Path to config file |
--name | (interactive) | Service name |
--description | (interactive) | Service description |
--auth | (interactive) | Auth type: api-key, oauth2, oauth1, custom |
--api-base | (interactive) | API base URL or sidecar URL |
--relative-target | false | Target is a relative path (for protocol translators) |
Auth type mapping:
| Auth type | Connector | Default api_base |
|---|---|---|
api-key | direct | user-provided |
oauth2 | sidecar | http://oauth2-refresher:8081 |
oauth1 | sidecar | http://oauth-signer:8080 |
custom | sidecar | user-provided |
agentsec status
Check proxy health and print config summary.
agentsec status [--config agentsec.yaml] [--proxy-url http://localhost:3100]agentsec logs
Display formatted audit log entries.
agentsec logs [--log-file ./audit.jsonl] [--tail 20]| Flag | Default | Description |
|---|---|---|
-l, --log-file | ./audit.jsonl | Path to audit log |
-t, --tail | 20 | Number of recent entries (0 = all) |
agentsec test
Validate config syntax and check that all agent credential references exist.
agentsec test [--config agentsec.yaml]SQLite-backed Commands
These commands manage agents, roles, and credentials via SQLite with encrypted storage. They support RBAC (role-based access control) where an agent’s effective permissions are the union of its roles’ credentials and its direct credential assignments.
All SQLite commands require --encryption-key (or set AGENTSEC_ENCRYPTION_KEY env var) and --db (default ./agentsec.db).
agentsec agent
agentsec agent list
agentsec agent create --name my-agent [--description "..."] [--roles reader,writer] [--credentials slack] [--rate-limit 100]
agentsec agent show <name>
agentsec agent enable <name>
agentsec agent disable <name>
agentsec agent delete <name>| Subcommand | Description |
|---|---|
list | List all agents with status |
create | Create a new agent (generates API key, prints it once) |
show | Show agent details and effective permissions (roles + direct credentials) |
enable | Re-enable a disabled agent |
disable | Disable an agent (blocks all requests) |
delete | Delete an agent |
agentsec role
agentsec role list
agentsec role create --name reader [--description "Read-only access"] [--credentials slack,github] [--rate-limit 50]
agentsec role add-credential <role> <credential>
agentsec role remove-credential <role> <credential>
agentsec role delete <name>| Subcommand | Description |
|---|---|
list | List all roles |
create | Create a role with optional credentials and rate limit |
add-credential | Grant a credential to a role |
remove-credential | Revoke a credential from a role |
delete | Delete a role (cascading — removes from agents) |
agentsec migrate
Import an existing agentsec.yaml into SQLite. Credential values are read from AGENTSEC_CRED_* env vars and stored encrypted (AES-256-GCM).
agentsec migrate --config agentsec.yaml --db agentsec.db --encryption-key $AGENTSEC_ENCRYPTION_KEY| Flag | Default | Description |
|---|---|---|
-c, --config | ./agentsec.yaml | YAML config to import |
-d, --db | ./agentsec.db | SQLite database path (created if missing) |
--encryption-key | $AGENTSEC_ENCRYPTION_KEY | 64 hex chars for AES-256-GCM |
This creates credentials, agents, and policies in the database. Agents are assigned their credentials directly (no roles created during migration).