Panoptes CLI

An npm-packaged terminal client for the existing Panoptes server. Includes 118 API command mappings plus register/login/logout and local profile management. Requires Node 22+ and a Panoptes backend (hosted at https://www.panoptes.software).

Start from this repository

After installing the package, the primary command is pnpt:

pnpt -v
pnpt register
→ https://www.panoptes.software/register (create your account in the browser)
pnpt login
Email: [email protected]
Password (hidden):
Logged in successfully as [email protected].

Fresh installations use https://www.panoptes.software, matching the application URL declared by this repository. No server question is asked. Running pnpt login while already signed in prints the saved identity and exits without prompting; run pnpt logout first to switch accounts. A rejected login prints an error (with a link to the signup page) and exits unsuccessfully. The panoptes executable remains an alias. The live production endpoint at https://www.panoptes.software is verified by pnpt status.

npm run cli:build
npm run cli -- login
npm run cli -- aws vm list
npm run cli -- security findings
npm run cli -- --help

Login prompts for Email and Password (hidden). On first login, the server is saved as the default profile. Subsequent commands reuse that server and session. Passwords are never written to configuration or session files.

Install the local package

cd packages/cli
npm pack
npm install -g ./panoptes-cli-0.1.1.tgz
pnpt login
pnpt aws vm list

The global install exposes pnpt (and the panoptes alias) on npm's executable path. The package has no runtime dependencies. Install the published package directly:

npm install -g panoptes-cli
pnpt login
pnpt aws vm list

Everyday commands

pnpt status
pnpt whoami
pnpt overview
pnpt vm list
pnpt aws vm list --region us-east-1
pnpt azure vm list
pnpt gcp vm list
pnpt aws s3 list
pnpt azure storage list
pnpt gcp storage list
pnpt aws vm stop RESOURCE_ID
pnpt security scan --account ACCOUNT_ID
pnpt security findings --severity critical
pnpt billing summary
pnpt k8s pods
pnpt ai ask "Where is our cloud spend increasing?"
pnpt resources export --file inventory.csv
pnpt vm list --json

IDs are Panoptes IDs from list output, not EC2 IDs or display names. Provider-prefixed VM writes verify that the ID belongs to that provider before sending the action. Storage currently supports inventory/export; this is not an S3 object upload/download/delete client.

Help and command groups

pnpt --help lists all commands. Module help and command help include flags, required arguments and examples:

pnpt aws --help
pnpt aws vm --help
pnpt vm start --help
pnpt schedules create --help
pnpt help k8s deployments scale

| Group | Available workflows | | --- | --- | | register / login / logout / whoami | Browser signup guidance, email/password session, local clearing, identity | | profile | List, set and use server profiles | | status / overview / search | Health, dashboard summary and resource search | | resources / vm / storage | Inventory, filters, stats, exports; VM start/stop/restart | | accounts | List, connect, update, test, sync, disconnect | | billing / subscription | Costs, trends, service breakdown, forecast, plans, invoices, exports, checkout/portal links, subscription usage | | schedules | Create/update/delete daily VM auto-stop schedules | | alerts / anomalies | Budget rule CRUD/reset; anomaly list/acknowledge/dismiss | | security | Summary, scan, findings, acknowledge/resolve, exports | | optimization | Summary, scan, recommendations, status tracking, exports | | approvals | Request, list, approve/reject, execute supported actions | | iac / drift | State upload/list/delete/check; findings, summary, resolve, export | | k8s | Cluster connection/sync/removal; nodes, pods, namespaces, logs, metrics, events; pod restart/delete; deployment list/scale | | ai | Ask, history and configuration availability | | reports / audit | Executive report and audit history/exports | | team / invitations | List users, change roles, invite/revoke/list/lookup invitations | | slack / webhooks | Connection CRUD, test, delivery history, webhook secret rotation | | deliveries | Inspect attempts and re-deliver | | account | Data export/deletion request, registration, password recovery/change, 2FA enrollment/verification/disable |

Provider prefixes work on commands with a provider filter, account connection/listing and VM power actions. Other commands use exact resource/account IDs, or operate on the organization. Unsupported combinations fail rather than silently ignoring the provider.

Connection and file examples

pnpt aws accounts connect --name staging --region us-east-1 --credentials-file aws.json
pnpt azure accounts connect --name production --credentials-file azure.json
pnpt gcp accounts connect --name analytics --credentials-file service-account.json
pnpt accounts sync ACCOUNT_ID
pnpt schedules create --resource RESOURCE_ID --time 18:30 --timezone Asia/Karachi
pnpt alerts create --amount 200 --provider aws
pnpt iac upload --account ACCOUNT_ID --name production --state-file terraform.tfstate
pnpt k8s clusters connect --name production --provider eks --kubeconfig-file config.yaml
pnpt k8s deployments scale CLUSTER_ID default api --replicas 3
pnpt slack connect --url-file slack-url.txt --channel operations
pnpt webhooks create --url-file webhook-url.txt --events "security.*,anomaly.detected"

AWS credential JSON uses accessKeyId, secretAccessKey and optional region. Azure uses tenantId, clientId, clientSecret, subscriptionId. GCP accepts a standard service-account JSON file (wrapped by the CLI), or the backend's { "serviceAccountJson": "...", "projectId": "..." } shape. Credentials are sent only to the selected HTTPS backend; keep these files out of source control.

Boolean body flags take explicit values, e.g. --enabled false, --active true. Complex input comes from files; there is no arbitrary shell evaluation. Terraform/kubeconfig content is sent in the API's JSON envelope.

Terminal output and automation

• Readable tables, headings and progress on a terminal with a soft pastel color scheme: blue table headers, tinted keys, and status/severity values shaded by state (healthy = soft green, degraded = soft amber, critical = soft coral). Colors auto-disable when output is piped, and --no-color or NO_COLOR turns them off completely; JSON output is always plain.
• --json or --output json emits structured stdout. Errors/prompts/progress use stderr. Tables abbreviate wide values and show primary fields; JSON retains full values and metadata.
• Inventory displays cached records, not a guaranteed live cloud snapshot. Use accounts sync and inspect its result before listing again.
• Use API-supported --page, --limit, or cursor flags shown by help. There is no hidden fetch-all; reported totals/cursors retain the server's limits.
• Mutations require confirmation, or --yes for intentional automation. The prompt identifies server and target. --non-interactive prevents prompts.
• Destructive actions check server 2FA status before submitting. When enabled, an authenticator code is requested with hidden input. Noninteractive 2FA-required writes fail; --yes cannot bypass authorization, plan restrictions, approvals or 2FA.
• Exports require --file PATH; existing files are protected unless --overwrite is explicit. Files preserve the server's CSV/XML/XLSX/JSON response, without inventing a format. Match the extension to the endpoint format.
• Webhook creation/secret rotation and 2FA enrollment intentionally display the newly issued secret. Save it securely and avoid capturing those outputs in shared logs.
• No automatic mutation retries. A timeout can occur after the server accepted work; inspect state/audit before retrying. Default deadline is 30 seconds, configurable with --timeout MS up to 300000.
• Billing checkout/portal commands print a browser URL; payment entry happens in the browser. AI suggestions never automatically execute actions.

Exit codes: 0 success, 1 local/unexpected failure, 2 invalid input/config/API validation, 3 authentication failure, 4 permission/plan denial, 5 network/upstream/unhealthy server, 6 interactive confirmation or 2FA required, 7 rate limited, 130 cancelled. Degraded health also exits 5 while preserving its response.

For CI login, supply PANOPTES_EMAIL and PANOPTES_PASSWORD through your CI secret store, then use login --non-interactive. Do not pass passwords as command-line flags. Long-term scoped automation tokens are a future server capability.

Sessions and profiles

pnpt profile set production --server https://your-panoptes.example
pnpt profile use production
pnpt profile
pnpt login
pnpt logout
pnpt logout --local

Config is stored in ~/.panoptes/config.json, or PANOPTES_CONFIG_DIR. Session files are separate and keyed by the exact normalized server URL, preventing credentials from being reused against another server. pnpt register prints the browser signup URL for the selected server. pnpt login skips credential prompts when a saved session already exists for that server; pnpt logout prints a notice when there is nothing to clear.

Windows session contents use CurrentUser DPAPI encryption through hidden, noninteractive Windows PowerShell. Linux/macOS use owner-only session files (0600 in a 0700 session directory), not an OS keychain. Treat those files as credentials. The CLI stores session cookies, expiry and account email only; passwords are never persisted. Login creates its own session through NextAuth's CSRF-protected credentials flow; it does not read browser cookies.

Sessions follow the existing server's expiry, lockout, role/tenant checks and security behavior. Logout signs out and removes the local session; the existing JWT backend does not centrally revoke copied JWTs. Google-only accounts are not supported by password login unless they have a configured password. Browser/device login and revocable scoped tokens remain future enhancements.

Server precedence: --server > PANOPTES_SERVER > selected profile > https://www.panoptes.software. Profile precedence: --profile > PANOPTES_PROFILE > saved default. An explicit different server does not overwrite an existing default profile. HTTPS is required except for loopback HTTP. Base paths are supported; redirects are never followed with credentials. Local development still uses pnpt login --server http://localhost:3000 once, or a saved local profile.

Validation and limits

npm run cli:test

Tests check command routes/methods against repository source, request contracts, profile/health behavior, login/session persistence, provider filters, confirmation, 2FA blocking, exports, permission failures and logout against a local HTTP fixture. These are not live AWS/Azure/GCP or payment tests.

The CLI exposes implemented server operations. It does not add missing backend capabilities such as VM creation/deletion, S3 object management, user removal (no DELETE users API), pod exec/streaming follow, multi-org membership, SSO/SCIM or unimplemented remediation. Account deletion follows the existing server's scheduling behavior; the CLI does not implement a deletion worker. Public status/marketing pages and Stripe's inbound webhook are not user commands.

Published to the npm registry as panoptes-cli. Remaining validation: macOS/Linux execution, provider acceptance tests and cross-platform CI. The root roadmap records remaining production milestones.