Command-line interface

Overview

You sign in through the portal in your browser, so your password and multi-factor authentication are used, and the CLI never sees them.
The CLI receives a session for your account in your current organisation. It has exactly your permissions: commands you are not allowed to run return 403.
There are no long-lived API keys. Sessions end after 30 minutes of inactivity or 12 hours at most.

Installation

pipx install ./cydra-cli          # or: python -m pip install ./cydra-cli
cydra --version

$ cydra login
To sign in, open:  https://app.cydralabs.com/cli
and confirm the code:  MRRG-HQQF
Do not approve it unless you started this sign-in yourself.

Signed in as you@example.com in Acme (security_admin).

cydra login opens the approval page in your browser (use --no-browser on a server and open the link elsewhere).
Sign in to the portal if needed, check that the code matches the one in your terminal, and choose Approve.
The CLI picks up its session within a few seconds. The request expires after 10 minutes.

Use --url for another deployment (for example your own cloud) and --profile to keep several sign-ins. To work in another organisation, switch organisation in the portal, then run cydra login again.

cydra whoami               # user, organisation, roles
cydra logout               # end this CLI session
cydra logout --all         # sign out of all devices, browser and CLI

Commands

Commands
Command	What it does	Permission
`agents list [--search] [--environment] [--status]`	List agents with status and risk	`agent:read`
`agents show ID`	Show one agent	`agent:read`
`agents suspend \| restore \| revoke ID --reason TEXT`	Kill switch: suspend, restore or permanently revoke an agent	`agent:control`
`policies list \| show ID`	Policies and their versions	`policy:read`
`policies publish ID VERSION`	Publish a draft version (you must not be its author)	`policy:publish`
`approvals list [--status] \| show ID`	The approval queue, with full context	`approval:read`
`approvals approve \| reject ID --reason TEXT`	Decide an approval request	`approval:decide`
`actions list \| show ID`	Action requests with decisions, approvals, execution and evidence	`action:read`
`actions cancel ID --reason TEXT`	Cancel a pending or approved action	`action:control`
`users list \| invite EMAIL --name NAME --role ROLE`	People and invitations	`user:read / user:manage + role:manage`
`evidence list \| verify`	Evidence records; verify the hash chain and signatures	`evidence:read`
`audit list [--action] [--outcome]`	The audit log	`audit:read`
`api METHOD PATH [--data JSON] [--if-match N]`	Call any API endpoint as yourself	As the endpoint requires

Run cydra COMMAND --help for every option. Containment, cancelling and publishing ask for confirmation; pass --yes to skip it in scripts. Reasons are recorded in the audit log and the evidence chain. The API reference lists every endpoint available through cydra api.

Scripting

# JSON output for any command
cydra agents list --environment production --json | jq -r '.[] | select(.risk_band == "critical") | .id'

# Raw API calls
cydra api GET /dashboard
cydra api POST /graph/rebuild

# Fail a check when the evidence chain is broken (exit code 1)
cydra evidence verify

Exit codes
Code	Meaning
0	Success
1	The request failed (for example a permission error), or evidence verification found a break
2	Confirmation was required or refused
3	Not signed in, or the session ended: run cydra login

Sessions are personal and short-lived, so the CLI is meant for people. For unattended automation, register an agent with a workload identity and use the agent SDK or the gateway API.

Security

Never approve a code you did not start. Someone could send you a link with their own code; approving it would give them a session with your permissions. The approval page shows the device name and IP address.
CLI sign-ins can be approved from a portal session and never from another CLI session.
Each approval is written to the audit log and the security log, and you receive an email about it (except for the shared demonstration accounts).
The session token is stored in ~/.config/cydra/credentials.json (%APPDATA%\cydra on Windows), readable by your user account and no other. cydra logout ends the session on the server and removes it locally.
The token is sent as Authorization: Bearer and is tied to your user; it is never accepted as a browser cookie, and browser sessions are never accepted as CLI tokens.

Revoking access

Sign out of all devices in the portal (or cydra logout --all) ends every browser and CLI session for your account. Administrators can disable a user, which ends their sessions on the next request.

Applies to the CydraLabs proof-of-concept platform. Last updated 4 October 2026. Questions or corrections: contact us.