sernixa-cli 0.1.1

Official Sernixa CLI for policy-governed local AI agent actions

Sernixa CLI

The official terminal client for evaluating local AI-agent actions against the real Sernixa control plane.

From the repository root:

python3 -m venv .venv-cli
source .venv-cli/bin/activate
pip install -e packages/sernixa -e apps/cli
sernixa auth login
sernixa validate payload.json

The CLI defaults to https://api.sernixa.com. It never evaluates policy locally and never stores raw credentials outside the protected user configuration file.

Governance commands

Exit codes are stable for shell and CI use:

• 0: allowed / success
• 1: denied by policy
• 2: operational error such as config, parsing, auth, or network failure

Core commands:

sernixa validate payload.json
cat payload.json | sernixa validate --json
sernixa validate --from-claude < claude-hook-payload.json
sernixa validate --from-codex < codex-hook-payload.jsonl
sernixa validate-plan --agent-type codex 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 doctor --json

validate accepts plain Sernixa governance JSON by default. --from-claude and --from-codex parse provider-native hook payloads and map them into the same governance request before calling the real Python SDK Client.governance_test() endpoint.

watch currently validates newline-delimited JSON action streams:

generate-actions | sernixa watch --json --plan-stream -

It does not claim side-effect streaming enforcement for arbitrary child processes until the backend exposes a streaming governance contract.

validate-plan calls the canonical agent-plan governance endpoint. Plan files can be either a JSON array of steps or an object with a plan array. Each step uses the shared schema: tool_name, action, arguments, resource, and metadata. The backend records a governance_agent_plan_evaluated audit event with a redacted plan and plan hash.

Local agent hooks and MCP integrations

Print hook snippets:

sernixa hook claude
sernixa hook claude-desktop
sernixa hook codex --json

Best-effort install:

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

Repair stale or duplicate Sernixa-managed entries:

sernixa hook repair claude
sernixa hook repair claude-desktop
sernixa hook repair codex

Inspect all supported targets:

sernixa hook status
sernixa hook status --json

Sernixa resolves local agent config targets through the shared OS-aware target resolver. If an official target location is uncertain, the CLI reports the selected path, alternates found, and any uncertainty instead of inventing a hidden path.

Supported install/status targets:

• claude / Claude Code: global user JSON settings, default ~/.claude/settings.json, override SERNIXA_CLAUDE_CONFIG_FILE.
• claude-desktop / Claude Desktop: MCP server block in the official app config:
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json, with packaged %LOCALAPPDATA%\Packages\...\LocalCache\Roaming\Claude\claude_desktop_config.json fallbacks when they already exist
  • Linux: ~/.config/Claude/claude_desktop_config.json
  • override SERNIXA_CLAUDE_DESKTOP_CONFIG_FILE
• codex / Codex: global user config only. The resolver inspects ~/.codex/hooks.json and ~/.codex/config.toml. Both files may exist and both may contain hook state. Status reports hooks_json_present, inline_toml_hooks_present, detected_hook_sources, and sernixa_installed_in instead of pretending only one file is active. Install writes to the primary write target: existing hooks.json first, existing config.toml when hooks.json is absent, and hooks.json when neither exists. Overrides: SERNIXA_CODEX_HOOKS_FILE, SERNIXA_CODEX_CONFIG_FILE. Codex status also separates hooks_declared, hooks_enabled, and hooks_effective. A dedicated hooks.json declaration is treated as enabled by that file. Inline TOML hook declarations require an explicit enablement signal such as hooks.enabled = true or the status output will include an activation_hint.

Project-scoped .codex/ files are intentionally ignored by these commands unless a future command explicitly adds project mode. Existing files are backed up before changes. Empty configs are treated as empty. Invalid JSON/TOML fails closed with the exact broken file path and remediation guidance. If both Codex global files contain Sernixa-managed hooks, status reports a duplicate install and sernixa hook repair codex keeps the primary write target while removing duplicate Sernixa-managed entries from the alternate file.

sernixa hook status --json returns the same core fields for every supported target: target_id, target_name, supported, install_mode, config_format, candidate_paths, primary_write_target, existing_paths, parse_errors, detected_sources, sernixa_installed, sernixa_installed_in, wrapper_valid, malformed, hooks_declared, hooks_enabled, hooks_effective, activation_hint, and repair_hint. Serialized JSON paths are always absolute; human output may shorten paths for readability.

The installed hooks call sernixa hook run , which reads provider JSON on stdin, calls live Sernixa governance, and emits provider-specific deny JSON when policy blocks a tool call.

Bootstrap

sernixa init
sernixa init --chat
sernixa init --claude
sernixa init --codex

init requires an interactive terminal, validates the API key before writing config, writes the config with private file permissions, and never echoes the key back to the terminal.

For chat agents, use the Python SDK adapter layer:

from sernixa import Client
from sernixa.adapters import SernixaAgentGuard, chat_plan_step

guard = SernixaAgentGuard(Client(), agent_type="chat", user_identity=user, context=context)
guard.declare_plan([chat_plan_step(tool_name="calendar.create", action="calendar.write", arguments=args)])
guard.execute_tool(calendar_create, tool_name="calendar.create", action="calendar.write", arguments=args)

Deferred audit commands

sernixa events, sernixa decisions, and sernixa replay are present but return operational errors until the backend exposes supported audit listing / decision replay endpoints for CLI use.