Sernixa CLI

The official terminal and local-agent integration for Sernixa governance. The CLI evaluates actions against the real Sernixa control plane, installs supported agent hooks and MCP configuration, launches safe local discovery, and exposes operational evidence without a dashboard-only workflow.

Install and set up

macOS and Linux:

python3 -m pip install --upgrade sernixa-cli
sernixa auth login
sernixa protect

Windows PowerShell:

py -m pip install --upgrade sernixa-cli
sernixa auth login
sernixa protect

The CLI and bundled Codex/Claude plugins share release compatibility version: 0.6.11. The upgrade command selects the latest release; verify it with sernixa --version.

sernixa auth login opens the Sernixa sign-in page, displays a short confirmation code, and stores a revocable CLI session after approval. The session inherits the signed-in user's organization, role, plan, and feature entitlements. Check the active identity without exposing its credential:

sernixa auth status

For an interactive API-key login, use the hidden prompt:

sernixa auth login --api-key

Organization API keys remain available for CI and other non-interactive automation. Send the key over stdin so it is not saved in command history:

Get-Clipboard | sernixa auth login --api-key-stdin

The key is never passed as a command-line argument or printed.

You can also run sernixa before authenticating. The console then shows only the focused sign-in choices:

sernixa › /login
sernixa › /api-key

The CLI validates the stored credential against the live identity and plan endpoints before treating the session as signed in. Missing, expired, rejected, or otherwise unverifiable credentials do not reveal the protected workflow catalog. After authentication, the running console refreshes in place. Type / to open the selectable command palette, use the arrow keys, and press Enter:

sernixa › /account
sernixa › /logout
sernixa › /status
sernixa › /policy
sernixa › /plan
sernixa › /exec
sernixa › /approval
sernixa › /discover
sernixa › /protect
sernixa › /integrations
sernixa › /events
sernixa › /approvals
sernixa › /evidence
sernixa › /passport
sernixa › /mcp
sernixa › /exit

The console is project-aware, remains open across commands, supports tab completion and private local history, and dispatches only Sernixa commands. History retains command names only: free-form arguments, sign-in, and subprocess commands stay out of saved history and the up-arrow menu. Legacy @ aliases remain accepted; use / to open the menu. Typing the first / opens the temporary prompt-toolkit dropdown with action descriptions, filtering, and arrow-key selection. The catalog stays in the dropdown and is not written into terminal scrollback. The palette, tab completion, startup panel, and help text show only actions appropriate to the current live session and authenticated plan. Login actions disappear after sign-in and return immediately after logout. Switching an organization refreshes the current account, plan, and available commands. A protected command typed manually while signed out is rejected locally, and authenticated commands remain checked by the backend. Slash commands accept arguments, for example /org-switch org_123 or /policy request.json. Every normal command such as validate request.json also works inside the authenticated console. Bare sernixa remains concise when stdout or stdin is not a terminal, so scripts and CI never hang; sernixa shell is the explicit interactive entry point.

sernixa protect is the recommended first run. It detects installed Codex, Claude, and Cursor hosts, validates live organization policy access, installs Sernixa as a first-class Codex and Claude Code plugin, configures the supported Cursor boundary, and prints the actual coverage limitations instead of claiming control over host events that were never emitted:

sernixa protect
sernixa protect --status
sernixa protect --target codex --target claude
sernixa protect --dry-run --json

After installation, restart open agent hosts. In Codex, open /plugins; in Claude Code, open /plugin. Select Sernixa Security and trust its UserPromptSubmit and PreToolUse hooks, plus its MCP server, when prompted. Start a new agent task after changing trust. Then run:

sernixa protect --status
sernixa doctor --strict

Protection is ready only when the plugin is visible and both required hooks are active. Plugin visibility alone is reported as needing hook approval. Once each plugin is ready, Sernixa removes only its own older standalone hook/MCP blocks (with backups), so the same enforcement command is not registered twice. The plugin still contains a hook because pre-tool blocking requires one; it is owned and displayed as part of the plugin rather than user config. sernixa setup remains available for the broader developer setup, including Claude Desktop and the bounded sernixa:// dashboard launcher. It preserves unrelated entries, backs up changed files, and reports host restart or hook-trust steps. Preview it without changing files:

sernixa setup --dry-run
sernixa setup --target codex --target cursor --json

For local repository development:

python3 -m venv .venv-cli
source .venv-cli/bin/activate
pip install -e packages/sernixa -e packages/sernixa-agent -e apps/cli

The CLI defaults to https://api.sernixa.com. Stored credentials use the platform user-config directory and mode 0600 on Unix. SERNIXA_ACCESS_TOKEN, SERNIXA_API_KEY, and SERNIXA_BASE_URL override the stored configuration for non-interactive use.

One-command Auto Discover

sernixa discover
sernixa discover --json
sernixa discover --job discjob_0123456789abcdef0123456789abcdef

The command validates auth, initializes the supported local agent when needed, passes the stored credential only through the one-shot child-process environment, enrolls the stable machine ID, creates or accepts a policy-scoped job for that machine, runs one sync/task cycle, and waits for the terminal job result. The credential is not printed or duplicated into a second token file.

The Command Center opens the same flow through sernixa://discover after a direct user click and an OS/browser confirmation. The native URL accepts only the fixed discovery action and an optional validated job ID; it cannot carry commands, credentials, paths, or environment values. If the launcher is unavailable, the dashboard shows the exact fallback command.

Discovery candidates are observations for review. Enrollment is inventory. An accepted agent sync is evidence, not online-presence proof. After discovery, select the exact MCP client config entries in the Registry and choose Approve & activate. Sernixa approves only that selection, sends a device-bound activation task to the principal that ran discovery, and the agent replaces each selected host entry with the fail-closed Sernixa proxy. Port and process observations remain review-only because they do not identify an exact host route. The UI reports Protection active only after an API-authorized governed tool call is observed.

Codex, Claude, and Cursor

Supported global targets:

• claude: a visible Sernixa Security plugin containing enforcement/lifecycle hooks, the Sernixa MCP server, and a protection skill. Users can inspect it from /plugin.
• claude-desktop: real stdio MCP server in the OS-specific Claude Desktop configuration.
• codex: a visible Sernixa Security plugin containing the enforcement hook, Sernixa MCP server, and protection skill. Users review/trust the plugin hook, and can inspect it from /plugins.
• cursor: global MCP entry in ~/.cursor/mcp.json, shared by Cursor IDE and CLI.

sernixa protect is the supported automatic installer. Anyone can also add the public repository marketplace directly:

codex plugin marketplace add abhishekdhull63/Sernixa.ai-Web
codex plugin add sernixa@sernixa

claude plugin marketplace add abhishekdhull63/Sernixa.ai-Web
claude plugin install sernixa@sernixa --scope user

Inside Claude Code, the equivalent interactive commands are /plugin marketplace add abhishekdhull63/Sernixa.ai-Web, /plugin install sernixa@sernixa, and /reload-plugins.

The legacy config installer remains available for Claude Desktop, Cursor, and older host builds:

sernixa hook install claude
sernixa hook install claude-desktop
sernixa hook install codex
sernixa hook install cursor

sernixa hook repair cursor
sernixa hook status

Inspect the current signed authority and explain one concrete proposed call without exposing the original prompt or secret arguments:

sernixa intent status
sernixa intent explain git.push \
  --tool git \
  --arguments '{"argv":["git","push","origin","HEAD:main"]}' \
  --resource '{"repo":"github.com/acme/project","branch":"main"}'

intent explain returns the deterministic authority relationship, exact delta, reason codes, and constraints. Gemini and RAG are skipped when the signed contract is sufficient.

Claude Code and Codex hooks call sernixa hook run <provider> before tool execution and record privacy-bounded session, tool, subagent, and compaction lifecycle evidence. allow continues through normal host permissions and deny blocks. Claude Code maps review to its supported human prompt. Current Codex PreToolUse does not support an ask result, so Sernixa maps review to a fail-closed deny with an explicit human-review reason instead of returning a hook shape that Codex would ignore. A policy-evaluation API or configuration failure exits with code 2, which both hosts treat as blocking; there is no local allow fallback. Observational lifecycle delivery is silent and non-blocking because a telemetry outage after an action cannot safely reverse that action.

Hook handlers allow 35 seconds. Hook HTTP phases are capped at 8 seconds with no SDK retries, so dependency failures can return the host's blocking exit code instead of waiting through retries until the host kills the hook. Ordinary CLI requests retain their configurable timeout and retries. Disabled, untrusted, or host-killed hooks are outside this command's enforcement boundary.

Hook proofs and passports are isolated by hashed credential, API, host, session, and workspace context, so concurrent sessions cannot overwrite each other. MCP passport calls may pass context.session_id with context.cwd; without a session ID, only one unexpired matching local proof may be selected. Ambiguity or credential rotation requires the exact session or a new human prompt, never the most recent session. The backend still verifies the signed proof. Explicit SERNIXA_INTENT_PROOF_FILE / SERNIXA_PLAN_SESSION_FILE overrides and ordinary CLI/SDK default paths remain unchanged; old state is not migrated or deleted. Codex PostToolUse also runs for failed commands. Sernixa records structured failure/success results when available and otherwise records observed, not succeeded. Plain output, runner help, and collection-only commands cannot become passing test/build evidence. Claude retains its documented separate PostToolUseFailure lifecycle. Use sernixa intent complete <contract-id> only when the human-authorized task is finished. Stop, compaction, and reconnect hooks never complete it automatically.

Claude Code, Claude Desktop, Codex, and Cursor run sernixa mcp serve. The stdio MCP server exposes the existing policy, plan, passport, and identity tools plus universal intent diagnostics:

• sernixa_policy_check: evaluate one proposed action.
• sernixa_plan_check: evaluate a declared multi-step plan.
• sernixa_execution_passport: issue and persist a signed, exact-step Execution Passport for an allowed plan.
• sernixa_identity: validate auth and return non-secret principal metadata.
• sernixa_intent_status: return the current signed task boundary.
• sernixa_intent_explain: normalize one candidate call and explain its authority relationship.

MCP tools provide explicit model capabilities; the installed hooks are the local tool-call enforcement points.

Execution Passports

Sernixa governs agent-added behavior, not legitimate human direction. The Codex and Claude UserPromptSubmit hooks turn the direct request into a short-lived proof of intent. For release instructions, the CLI also signs the current Git remote, branch, package manifests, and versions into a narrow explicit-human-authorization bundle. Git pushes use a sernixa.git_operation_target.v1 resource that preserves the repository, branch, commit, destination, force flag, rollback policy, and a server-verified human-authorization marker through plan evaluation and hook enforcement. Single tool checks and complete plan checks use that proof automatically:

• exact work within the verified request and current project can proceed while retaining its risk classification and evidence;
• an explicitly requested current-repository push, release/tag, in-workspace package or docs publication, or environment-scoped deployment can proceed without a second blocking prompt when its signed target and prerequisites match;
• scope introduced by the agent, a different project or destination, changed arguments, or unclear intent remains reviewable;
• unrelated repositories/packages, unrequested deployment, secret or role changes, destructive history operations, and force-push without separate explicit authorization are denied;
• hard organization policy, failed security infrastructure, plan drift, invalid or expired proof, and replay still fail closed.

If no organization-uploaded Rego rule matches, Sernixa reports that it applied the built-in/default policy fallback. This is a normal policy source choice, not an error or an automatic review.

An approved plan is not a reusable local “allow.” Sernixa signs each exact tool/action/arguments/resource binding, and the API atomically consumes the matching proof once before execution. Changed arguments, undeclared tools, expired tokens, and replayed steps fail closed.

Issue or inspect a passport directly:

sernixa passport issue --agent-type codex plan.json
sernixa passport issue --agent-type codex --plan-id plan_123 --approval apr_123 plan.json
sernixa passport status
sernixa passport clear

When a plan still requires review, the first result includes one approval_id. Approve it through the existing approval workflow, then retry the unchanged plan with the returned plan_id and approval_id. Sernixa consumes that approval once when it issues the passport; it cannot authorize a changed plan or override a current policy denial.

In Codex, Claude, Cursor, or another MCP host, ask the model to call sernixa_execution_passport with its complete intended plan before it begins tool use. The installed Codex/Claude pre-tool hook then consumes the matching proof for each emitted tool event. The passport authorizes only the declared steps; it never executes them and never bypasses native host permissions.

Coverage remains explicit: no integration can block a capability that the host does not expose through a hook or MCP call. On current Codex Windows builds, Sernixa remains available as a plugin and MCP policy/passport layer, while pre-tool blocking depends on Codex adding Windows hook support.

Governance and execution

sernixa validate payload.json
cat payload.json | sernixa validate --json
sernixa validate --from-claude < claude-hook.json
sernixa validate --from-codex < codex-hook.jsonl
sernixa validate-plan --agent-type codex plan.json
sernixa validate-many --output json policies/*.json
sernixa exec --plan plan.json -- npm test
sernixa codex-exec --plan codex-plan.json -- codex exec "fix lint"

sernixa exec accepts exactly one shell.execute step and requires its declared argv to match the child argv exactly:

{
  "plan": [
    {
      "tool_name": "Shell",
      "action": "shell.execute",
      "arguments": { "argv": ["npm", "test"] }
    }
  ]
}

Exit codes are stable:

• 0: success or policy allow
• 1: deny, review required, invalid evidence, or non-success terminal result
• 2: configuration, parsing, auth, network, or API failure

Human output is intentionally concise. Use --json when a script needs one structured record. Plan and execution envelopes report policy explanations, proof counts, authorization IDs, child exit status, stdout, and stderr without printing plan tokens, proof signatures, or nonces.

validate-plan calls the canonical plan endpoint. exec evaluates one exact command step, rejects argv drift before policy evaluation, consumes the matching one-time proof, and only then starts the child process. codex-exec activates the complete Execution Passport for child Codex hooks; each emitted tool event must consume its own exact proof. A generic child process is never described as multi-step enforcement when it has no Sernixa hook boundary.

Audit, approvals, evidence, and Flight Recorder

sernixa events --limit 25
sernixa events --type governance_agent_plan_evaluated --json

sernixa approvals list
sernixa approvals decide approval_123 approved --reason "Reviewed bounded deployment."
sernixa approvals decide approval_456 rejected --reason "Production scope is too broad."
sernixa approvals wait approval_123 --json

sernixa evidence export --approval approval_123 --output approval-evidence.json
sernixa evidence export --from 2026-07-01T00:00:00Z --to 2026-07-31T23:59:59Z --output july-evidence.json --json
sernixa evidence verify approval-evidence.json --json

sernixa flight verify
sernixa flight verify --stream stream_123 --json
sernixa flight collectors

These commands call authenticated organization endpoints and inherit backend permissions and feature entitlements. approvals wait follows one server-side approval ID until a terminal state and never executes a command merely because a local poll returned approved. Evidence export asks the backend to generate and verify the bundle before writing it atomically with mode 0600 on POSIX. Invalid bundles are not written; unsigned local-demo evidence remains explicitly labeled unsigned_local_demo. sernixa decisions remains a backward-compatible alias for the pending approval queue. Replay is not claimed because the backend does not expose an authorized decision-replay endpoint.

Stable configuration overrides

• SERNIXA_CONFIG_FILE
• SERNIXA_ACCESS_TOKEN
• SERNIXA_CLI_TIMEOUT_SECONDS
• SERNIXA_PLAN_SESSION_FILE
• SERNIXA_HISTORY_FILE
• SERNIXA_CLAUDE_CONFIG_FILE
• SERNIXA_CLAUDE_DESKTOP_CONFIG_FILE
• SERNIXA_CODEX_HOOKS_FILE
• SERNIXA_CODEX_CONFIG_FILE
• SERNIXA_CURSOR_CONFIG_FILE

Project-scoped Codex files are intentionally not modified by global setup. Invalid JSON or TOML fails closed with the exact path and a repair command. Existing files are backed up before material changes.

Release compatibility version 0.6.11 requires the matching strict-host API. Package installation alone does not prove protection: complete host trust and a fresh signed allow/deny check before enablement. Platform and host acceptance are recorded separately in the release evidence. Version 0.6.10 tags did not produce registry releases.