Metadata-Version: 2.4
Name: sernixa-cli
Version: 0.4.10
Summary: Official Sernixa CLI for policy-governed local AI agent actions
Author: Sernixa Team
License-Expression: MIT
Project-URL: Changelog, https://github.com/abhishekdhull63/Sernixa.ai-Web/tree/main/apps/cli/CHANGELOG.md
Project-URL: Homepage, https://sernixa.com
Project-URL: Repository, https://github.com/abhishekdhull63/Sernixa.ai-Web
Project-URL: Documentation, https://github.com/abhishekdhull63/Sernixa.ai-Web/tree/main/docs/cli.md
Keywords: sernixa,cli,governance,agents,policy
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: platformdirs>=4.0.0
Requires-Dist: prompt-toolkit>=3.0.48
Requires-Dist: rich>=13.8.0
Requires-Dist: sernixa>=0.4.5
Requires-Dist: sernixa-agent>=1.6.1
Requires-Dist: typer>=0.12.0

# 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:

```bash
python3 -m pip install --upgrade sernixa-cli
sernixa auth login
sernixa protect
sernixa protect --status
```

Windows PowerShell:

```powershell
py -m pip install --upgrade sernixa-cli
sernixa auth login
sernixa protect
sernixa protect --status
```

`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:

```bash
sernixa auth status
```

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

```bash
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:

```powershell
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:

```text
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:

```text
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.
Typing the first `@` immediately renders the available actions with descriptions;
the prompt-toolkit selector remains active for filtering and arrow-key selection.
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. A protected command
typed manually while signed out is rejected locally, and authenticated commands
remain checked by the backend. `@` is the primary command-palette prefix and
slash-prefixed forms remain compatible. 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:

```bash
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 hook and
MCP server when prompted. Once each plugin is visible, 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:

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

For local repository development:

```bash
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

```bash
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 proof. No discovery result silently becomes a managed MCP server.

## 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:

```bash
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:

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

sernixa hook repair cursor
sernixa hook status
```

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 for the live policy request; the CLI request budget is 30 seconds. This prevents slow semantic evaluations from being killed by a shorter host-hook timeout.

Claude Code, Claude Desktop, Codex, and Cursor run `sernixa mcp serve`. The stdio MCP server exposes four non-mutating tools:

- `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.

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 exchange the direct prompt for a
short-lived, backend-signed proof of intent. The CLI stores that signed token
in a private local file; audit events retain its digest, not the prompt.
Single tool checks and complete plan checks use the proof automatically:

- an exact, bounded action aligned with the verified human request can proceed;
- added scope, a changed destination, or unclear intent remains reviewable;
- policy deny, extreme destructive scope, exfiltration, control bypass, plan
  drift, expiry, and replay still fail closed.

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:

```bash
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

```bash
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:

```json
{
  "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

```bash
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.
