Metadata-Version: 2.4
Name: antahkarana-cli
Version: 0.8.0
Summary: ant — the Antaḥkaraṇa governed-AI operator CLI: prompt your on-box copilot to investigate/operate a machine, read-only by default, with y/N approval for changes and catastrophic commands hard-blocked.
Author: Deepak Soni
License: Apache-2.0
Project-URL: Homepage, https://pypi.org/project/antahkarana/
Keywords: llm,agent,cli,security,mcp,antahkarana,governed,ssh
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# ant — Antaḥkaraṇa governed-AI operator CLI

Author — Deepak Soni. A tiny, dependency-free, cross-platform CLI (Windows / macOS / Linux) that prompts your
**on-box copilot** (the Antaḥkaraṇa model + control ring) from any terminal — Claude-Code style. It investigates
a machine, reasons, runs **read-only** commands immediately, and asks **y/N before any state-changing action**;
catastrophic commands (`rm`/`dd`/`mkfs`/`reboot`/…) are **hard-blocked** server-side.

PyPI: https://pypi.org/project/antahkarana-cli/  ·  command: `ant`

## Install
```bash
pip install antahkarana-cli          # or: pipx install antahkarana-cli
```

## First run
```bash
ant connect http://YOUR-BOX:8090     # point it at your copilot (saved to ~/.ant/config.json)
ant login dk-xxxxxxxx                 # the copilot requires an API key (dk- prefix); ant refuses without one
ant                                   # interactive session: banner + prompt
ant "what is listening on this server?"   # one-shot
ant status                            # connection + model health
```

## Commands
```
ant                         interactive REPL
ant "<prompt>"              one-shot
ant connect <url>           save the copilot endpoint
ant login <dk-key>          save an auth token (sent as Bearer)
ant logout                  remove the saved key
ant status                  connection + model health
ant new | ant forget        archive / clear conversation memory
ant audit verify <file>     verify a hash-chained audit bundle LOCALLY (offline governance)
ant version
```
In the REPL, slash commands: `/connect /login /logout /model /status /save [path] /new /sessions /resume <id>
/forget /audit verify <file> /version /help /exit`.

## Governance: verify an audit bundle offline
A governed copilot (antahkarana 4.0 platform) can export a **signed, hash-chained audit bundle**.
`ant audit verify <bundle.json>` recomputes the whole chain **on your machine** — no trust in the box
that produced it, no dependencies — and if a record was altered it tells you the exact index where the
chain breaks (exit code 1, so it drops straight into CI):
```bash
ant audit verify audit-bundle.json
#  ✓ audit chain intact — 128 record(s), hashes verify end-to-end
#  ✗ audit chain BROKEN at record index 41   (tamper localized)
```

## Governance: run the non-bypass proof offline
A governed copilot (antahkarana 5.0 self-governing) ships a **machine-checked** guarantee that no action
reaches a sink without a capability token minted by the control ring. `ant verify` runs that proof **on
your machine** — a zero-dependency, stdlib-only copy of the checker, so you don't trust the box's word for
it. It exhaustively checks the non-bypass invariants over the whole governance skeleton; `--teeth` also
fails three deliberately-broken models (a checker that can't fail proves nothing):
```bash
ant verify --teeth
#  ✓ INV-1/4/5 hold over all 291 reachable states
#  checker teeth (each broken model MUST fail):
#    INV-1 bypass          INV-1 violated - counterexample in 4 step(s)
#    INV-4 ignore-control  INV-4 violated - counterexample in 8 step(s)
#    INV-5 token-reuse     INV-5 violated - counterexample in 5 step(s)
```
This is behaviorally identical to the SDK's `atk verify` and `antahkarana.formal.check()` — same 291
states, same counterexamples — just with no dependency on the SDK.

## What you can ask
- `what OS is this and what's listening on its ports?` → runs read-only, reports
- `create a file /tmp/demo.txt` → proposes it, asks **[y/N]**, runs only if you approve
- `rm -rf /tmp/x` → **hard-blocked** by the control ring
- `assess example.com` → passive web-recon → prioritized report
- `summarize this file /path/to/notes.md` → **reads a LOCAL file** on your machine
- `write the summary to a file ~/Desktop` → **saves LOCALLY as plain text**, prints the path

## Features (0.6.0)
- **Offline non-bypass proof** — `ant verify [--teeth]` runs the machine-checked non-bypass invariant
  locally (zero-dependency, stdlib only); exhaustive over 291 reachable states, and `--teeth` fails three
  broken models. Behaviorally identical to the SDK's `atk verify`.
- **Offline audit verification** — `ant audit verify` checks a hash-chained audit bundle locally,
  zero-dependency, and localizes any tamper to the exact record index (matches the box's own verifier).
- **Multi-tenant aware `status`** — shows tenant/tier and governed-fleet size when the box reports them.
- **API-key auth** — refuses with "API key required" unless a `dk-` key is set.
- **Live progress** — a "thinking…/running <tool>" spinner while the agent works (TTY only).
- **Memory across runs** — your conversation persists in `~/.ant/session.json`, so `ant` remembers what you did;
  `/new` archives and starts fresh, `/sessions` + `/resume` revisit past ones, `/forget` clears.
- **Local file read** — paths you mention are read on YOUR machine and inlined for the copilot.
- **Local file write** — when you ask it to save/write, the reply is written locally as clean **text** (not
  markdown); give a folder/path or it defaults to `./ant-output-<time>.txt`, and the path is printed.

## How it works
`ant` is a thin client over the copilot's `/api/chat` — the model (e.g. Qwen2.5-14B), the governed `run_shell`,
the web-recon tools, and the control ring all live on the box (or a remote SSH target the copilot is pointed at).
The box governs and audits every command; **local file read/write happens on your own machine** by the CLI.

Requires a running Antaḥkaraṇa copilot (see `../copilot/`).
