Metadata-Version: 2.4
Name: sernixa-cli
Version: 0.1.1
Summary: Official Sernixa CLI for policy-governed local AI agent actions
Author: Sernixa Team
License-Expression: MIT
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: sernixa>=0.3.1
Requires-Dist: typer>=0.12.0

# Sernixa CLI

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

From the repository root:

```bash
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 <provider>, 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 <decision-id> are present
but return operational errors until the backend exposes supported audit listing
/ decision replay endpoints for CLI use.
