Usage & Secrets Commands
Monitor billing usage, manage API credentials, and query audit logs for compliance.
Usage Commands
Track API consumption and export usage data for billing integration.
cco usage summary
Show usage summary for the current billing period.
| Parameter | Type | Description |
|---|---|---|
--since |
ISO-8601 date string | Start date for usage calculation (optional). Defaults to the beginning of the current billing period. |
cco usage summary cco usage summary --since 2026-05-01
cco usage export
Export usage data for external billing systems or cost allocation reports.
| Parameter | Type | Description |
|---|---|---|
--format |
json | csv | Output format. Defaults to json. |
cco usage export --format json > usage.json cco usage export --format csv > usage.csv
Secrets Commands
Manage API keys and credentials for configured providers. Secrets are stored securely in the local config file.
Security Note: Always use cco secret backup before rotating secrets. The backup allows you to restore the previous configuration if the rotation fails.
cco secret list
List configured secrets. Shows environment variable names only - actual values are never displayed.
cco secret list
cco secret backup
Backup the current config before rotating a secret. Creates a timestamped backup file.
| Parameter | Type | Description |
|---|---|---|
--provider |
primary | fallback | Provider to backup. Defaults to primary. |
cco secret backup --provider primary
cco secret rotate
Rotate an API key for a provider. If --key is not provided, reads from stdin.
| Parameter | Type | Description |
|---|---|---|
--provider |
string | Provider name. Defaults to minimax. |
--key |
string | New API key. If not provided, reads from stdin. |
--force |
flag | Skip confirmation prompt. |
# Rotate with explicit key cco secret rotate --provider minimax --key sk-xxx # Rotate with stdin echo "sk-xxx" | cco secret rotate --provider minimax # Force rotation without confirmation cco secret rotate --provider minimax --key sk-xxx --force
Audit Commands
Query and export the audit log for compliance, debugging, and security auditing purposes.
What is Audit Logging?
Compliance and traceability for production environments
Audit logging records every significant event in CCO's operation:
- Run lifecycle - When runs start, complete, or fail
- Task execution - Commands executed and their outcomes
- Configuration changes - Provider switches, secret rotations
- Errors and warnings - Failures, rate limits, retries
- Usage tracking - API calls, token consumption
Audit logs are essential for:
- Compliance audits (SOC 2, ISO 27001)
- Security incident investigation
- Cost allocation by team or project
- Reproducibility verification
cco audit query
Query the audit log with optional filters.
| Parameter | Type | Description |
|---|---|---|
--since |
ISO-8601 datetime | Start of time range (optional). |
--until |
ISO-8601 datetime | End of time range (optional). |
--event-type |
string | Filter by event type (e.g., run_started, run_completed, task_executed). |
--limit |
integer | Maximum entries to return. Defaults to 100. |
--json |
flag | Output in JSON format. |
# Query all events from the last 24 hours cco audit query # Query specific event types cco audit query --event-type run_started cco audit query --event-type task_executed # Query with time range cco audit query --since 2026-05-01T00:00:00 --until 2026-05-08T23:59:59 # Query with limit and JSON output cco audit query --limit 50 --json
cco audit export
Export audit log entries in JSON or CSV format for external analysis.
| Parameter | Type | Description |
|---|---|---|
--since |
ISO-8601 datetime | Start of time range (optional). |
--until |
ISO-8601 datetime | End of time range (optional). |
--event-type |
string | Filter by event type. |
--format |
json | csv | Output format. Defaults to json. |
# Export all events to JSON cco audit export > audit.json # Export to CSV for spreadsheet analysis cco audit export --format csv > audit.csv # Export specific event type cco audit export --event-type run_completed --format json > completed_runs.json
Common Event Types
| Event Type | Description |
|---|---|
run_started |
A new orchestrator run was initiated |
run_completed |
A run completed successfully |
run_failed |
A run failed with an error |
task_executed |
A task command was executed |
task_completed |
A task completed successfully |
secret_rotated |
An API key was rotated |
config_changed |
Configuration was modified |
rate_limit_hit |
API rate limit was reached |