Metadata-Version: 2.4
Name: sernixa-cli
Version: 0.4.3
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.2
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 setup
sernixa doctor --strict
```

Windows PowerShell:

```powershell
py -m pip install --upgrade sernixa-cli
sernixa auth login
sernixa setup
sernixa doctor --strict
```

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

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.

Then run `sernixa` by itself to open the persistent governance console. Type
`@` to open the selectable command palette, use the arrow keys, and press Enter:

```text
sernixa › @status
sernixa › @discover
sernixa › @integrations
sernixa › @events
sernixa › @approvals
sernixa › @exit
```

The console is project-aware, remains open across commands, supports tab completion and private local history, and dispatches only Sernixa commands. The palette shows only actions available on the authenticated plan; direct commands are still 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 it. 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 setup` configures Claude Code, Claude Desktop, Codex, and Cursor, preserves unrelated entries, backs up changed files, registers the bounded `sernixa://` dashboard launcher, and reports host restart or hook-trust steps. Preview 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`: Claude Code enforcement and lifecycle hooks in `~/.claude/settings.json`, plus the Sernixa MCP server in `~/.claude.json`.
- `claude-desktop`: real stdio MCP server in the OS-specific Claude Desktop configuration.
- `codex`: enforcement and lifecycle hooks plus the Sernixa MCP server in `~/.codex`. Hooks are effective by default unless `[features].hooks = false`; users still review/trust new non-managed hooks in Codex.
- `cursor`: global MCP entry in `~/.cursor/mcp.json`, shared by Cursor IDE and CLI.

Install or repair an individual integration:

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

sernixa hook repair codex
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 three non-mutating tools:

- `sernixa_policy_check`: evaluate one proposed action.
- `sernixa_plan_check`: evaluate a declared multi-step 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.

## 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"
```

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` only when a script needs structured details; JSON decisions omit the duplicated raw backend payload.

`validate-plan` calls the canonical plan endpoint. `exec` and `codex-exec` run the child command only after every planned step is allowed and bound to its proof.

## Audit, approvals, 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 flight verify
sernixa flight verify --stream stream_123 --json
sernixa flight collectors
```

These commands call the authenticated organization endpoints and inherit backend permissions and feature entitlements. `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.
