@canaryai/cli 0.1.5 → 0.1.9

package/README.md

@@ -13,9 +13,17 @@ bun add -g @canaryai/cli
 ## Login
 
 ```bash
-canary login
+canary login              # production (default)
+canary login --env dev    # dev environment
+canary login --env local  # local development
 ```
 
+Options:
+- `--env <env>` - Environment to login to: `prod`, `dev`, or `local`
+- `--api-url <url>` - Custom API URL (overrides --env)
+- `--app-url <url>` - Custom app URL (overrides --env)
+- `--no-open` - Don't auto-open browser
+
 ## Quickstart (local testing)
 
 1) Start your app locally.
@@ -43,6 +51,49 @@ Tools:
 - `local_run_tests` (port, instructions, title)
 - `local_wait_for_results` (runId)
 
+## PSQL (superadmin only)
+
+Execute read-only SQL queries against the production database. Requires superadmin privileges and the `cli.psql.enabled` knob to be enabled.
+
+```bash
+canary psql "SELECT id, status FROM jobs LIMIT 5"
+canary psql "SELECT * FROM jobs WHERE status = 'running'" --json
+```
+
+Options:
+- `--json` - Output results as JSON instead of a table
+- `--query <sql>` - Alternative to positional query argument
+
+Limits:
+- Query size: 10KB max (for larger queries, use psql directly)
+- Query timeout: 30s default (configurable via `cli.psql.timeout_ms` knob)
+- Result rows: 10K max (results truncated if exceeded)
+
+### Security Model
+
+The read-only PostgreSQL user (`debug_agent`) provides the **primary security layer** - it has SELECT-only privileges enforced at the database level. Any modification attempts will fail at the database regardless of other controls.
+
+Keyword validation serves as a **secondary defense-in-depth** measure that:
+1. Prevents modification attempts from reaching the database
+2. Triggers Slack alerts and auto-disables the feature on suspicious activity
+3. Provides an audit trail of attempted misuse
+
+Blocked keywords include: INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, TRUNCATE, GRANT, REVOKE, VACUUM, REINDEX, COPY, EXECUTE, CALL, DO, PREPARE, SET, RESET, LOCK, COMMIT, ROLLBACK, LISTEN, NOTIFY.
+
+### Security Controls Summary
+
+| Control | Purpose |
+|---------|---------|
+| Superadmin auth | Only trusted operators can access |
+| `cli.psql.enabled` knob | Feature disabled by default, requires explicit enablement |
+| Read-only DB user | Database-level protection against modifications |
+| Keyword detection | Early blocking + alerting on suspicious queries |
+| Auto-disable | Feature self-disables on modification attempts |
+| Slack alerts | Immediate notification to security team |
+| Query timeout | Prevents long-running queries from impacting production |
+| Row limits | Prevents accidental full table dumps |
+| RDS query logging | Infrastructure-level audit logging of all queries
+
 ## Environment variables
 
 - `CANARY_API_URL` (default `https://api.trycanary.ai`)