AiNxt CLI is a terminal-based AI coding agent — a full-screen TUI that understands your codebase, edits files, runs shell commands, searches the web, and manages long-running tasks. Works with your own API key. No gateway required.
One Intelligence. Works for Everyone.
AiNxt brings intelligence into enterprise work, development environments, command-line workflows, and the foundations used to build new AI experiences. This repository is AiNxt CLI — AI in the terminal: ask, build, fix, automate, execute.
An initiative of NPCI — National Payments Corporation of India.
Four layers, read top-down: in the terminal (instruction · repo · shell · CI) → the loop (ask · plan · tool call · diff · confirm) → the same governed path (identity & access · guardrails · audit) → models (router · hosted providers · open-weight self-hosted). The CLI is the only surface that can change things on your machine — so the loop is deliberately explicit: it proposes, you confirm, then it acts.
| I want to… | My path |
|---|---|
| Use AiNxt CLI myself — my own API key, my own machine | ↓ Run the curl command below. Done in two minutes. |
| Deploy AiNxt CLI across a team — governed access, shared budgets, audit, model policy | ↓ Install below, then connect to the AiNxt gateway |
| Build from source — audit the code, contribute, or run an unreleased commit | Build from source — git clone + ./setup.sh (Rust toolchain, ~10 GB disk) |
| I want to… | My path |
|---|---|
| Install latest — no toolchain, no manual steps | ↓ Run the curl command below |
| Pin a specific version | curl -fsSL https://raw.githubusercontent.com/npci/ainxt-cli/main/install.sh | bash -s 0.2.101 (replace 0.2.101 with the version you want) |
| Verify checksum before installing | curl -fsSL https://raw.githubusercontent.com/npci/ainxt-cli/main/install.sh | AINXT_REQUIRE_CHECKSUM=1 bash |
macOS / Linux — install latest:
curl -fsSL https://raw.githubusercontent.com/npci/ainxt-cli/main/install.sh | bashPin a specific version (replace 0.2.101 with the version you want):
curl -fsSL https://raw.githubusercontent.com/npci/ainxt-cli/main/install.sh | bash -s 0.2.101Verify the checksum before the binary is placed on your machine:
curl -fsSL https://raw.githubusercontent.com/npci/ainxt-cli/main/install.sh | AINXT_REQUIRE_CHECKSUM=1 bashWindows (PowerShell):
irm https://raw.githubusercontent.com/npci/ainxt-cli/main/install.ps1 | iexWindows with Git Bash / MSYS2: use the
curl | bashform above — WSL uses the Linux binary.
The installer puts ainxt in ~/.ainxt/bin/ and adds it to your PATH (by appending to your shell profile). Open a new terminal after install and run ainxt --version to confirm it worked. No toolchain needed — it downloads a prebuilt binary for your platform.
Before starting
ainxtfor the first time, setAINXT_API_KEY— this is a separate startup check, needed even if your model's real credential lives elsewhere (aconfig.tomlenv_key, or the TUI model picker). If you don't have one yet, a placeholder works:export AINXT_API_KEY=local
You do not need an AiNxt gateway. Three ways to connect a provider — pick one:
Start ainxt, then open the model picker:
/model or Ctrl+M → + Add new model…
A guided form asks for the model id, base URL, API backend, and a credential — env var name (recommended) or a plaintext key:
Choosing the "Environment variable" credential mode asks for the variable's
name, not the key itself — the actual secret stays out of config.toml
entirely, read from your shell environment at runtime:
Typing a name here doesn't set it. You still have to export that variable
yourself in your shell (e.g. export ANTHROPIC_API_KEY=sk-ant-...) — ainxt
only reads whatever name you gave it, it never creates or stores the value.
It writes the entry to config.toml automatically. Restart ainxt — the
model won't appear in the picker (or be selectable via -m) in the session
you added it from, only in the next one.
Set three vars and run. Nothing is written to disk. Always AINXT_API_KEY
regardless of provider — this path has no per-provider credential, so the
provider's own key-name env var (ANTHROPIC_API_KEY, OPENAI_API_KEY, ...) is
never read here.
Anthropic
export AINXT_API_KEY=sk-ant-...
export AINXT_API_BASE_URL=https://api.anthropic.com/v1
export AINXT_API_BACKEND=messages
ainxt -p "explain this repo"OpenAI
export AINXT_API_KEY=sk-...
export AINXT_API_BASE_URL=https://api.openai.com/v1
export AINXT_API_BACKEND=responses
ainxt -p "explain this repo"Ollama (local, no key)
export AINXT_API_BASE_URL=http://localhost:11434/v1
export AINXT_API_KEY=local # placeholder — Ollama ignores it
ainxt -p "explain this repo"Define named models and switch between them with -m <name>.
Anthropic / Claude
[model.claude]
model = "claude-sonnet-4-6"
base_url = "https://api.anthropic.com/v1"
api_backend = "messages"
context_window = 200000
env_key = "ANTHROPIC_API_KEY"
[model.claude.extra_headers]
anthropic-version = "2023-06-01"export ANTHROPIC_API_KEY=sk-ant-...
ainxt -m claude -p "explain this repo"
ainxt -m claude # full TUIOpenAI / GPT
[model.gpt]
model = "gpt-4o"
base_url = "https://api.openai.com/v1"
api_backend = "responses"
env_key = "OPENAI_API_KEY"export OPENAI_API_KEY=sk-...
ainxt -m gptOllama (local, free, no key)
[model.local]
model = "llama3.2:latest"
base_url = "http://localhost:11434/v1"
api_backend = "chat_completions"export AINXT_API_KEY=local # placeholder — Ollama needs no real key
ainxt -m local
api_backendquick reference:
messages→ Anthropic Messages API (Anthropic only)responses→ OpenAI Responses API (OpenAI's newer format)chat_completions→ OpenAI-compatible/v1/chat/completions— works with any provider that speaks this shape: OpenAI (classic), Ollama, vLLM, LM Studio, Groq, Together AI, Mistral, and any self-hosted or proxy endpoint. Azure OpenAI needs anapi-versionquery param this doesn't send — see § All model providers below.
ainxt # full-screen TUI
ainxt -p "explain this repo" # headless, one-shot
ainxt -m claude -p "fix this" # specific model
ainxt -c # continue last session| Capability | Detail | Docs |
|---|---|---|
| Edits code | Reads, writes and patches files behind a permission layer | permissions & safety · sandbox |
| Runs commands | Shell execution with approval rules and an optional sandbox | permissions & safety · sandbox |
| Plans first | Proposes an approach before touching anything — you approve | plan mode |
| Delegates | Spawns subagents for parallel exploration and review | subagents · agent mode |
| Extends | MCP servers, skills, hooks and plugins | MCP servers · skills · plugins · hooks |
| Remembers | Sessions resume, fork and persist; project rules load automatically | memory · sessions · project rules |
| Scripts | Headless mode with plain, json and streaming-json for CI |
headless / CI mode |
| Drives editors | Same agent over ACP — powers the IDE plugins | AiNxt Code |
| Policy enforcement | Every tool call passes through ainxt-pep — Built-in Policy Enforcement Point — before it runs |
permissions & safety |
Full detail: User Guide — 24 chapters.
Every action the agent takes passes through two security layers built into the binary by NPCI, not bolted on after:
ainxt-policy — the decision engine. Holds a resolved SecurityPolicy and
answers per-action questions. Two invariants are unconditional:
- Sovereign actions can never be auto-approved — no flag, env var, YOLO mode, hook or settings source can bypass this. The check is structurally isolated from all configuration inputs.
- Capability gate — consequential actions below the
Workspacetrust tier are denied before they reach the model.
ainxt-pep — the Policy Enforcement Point. The single place a tool action is
authorised. Everything else in the stack describes or records; this is the one
that says no. Risk is charged before the verdict, so the action that trips a
budget is itself refused rather than being the last one allowed through.
OSS vs managed builds. The open-source binary ships with require_policy = false — permissive defaults, no signed bundle required. A managed enterprise
build sets require_policy = true and embeds an Ed25519 authority public key;
the CLI refuses to start without a valid signed policy bundle from that authority.
This is the single field that separates the two postures — no code change, no
rebuild.
It proposes, you confirm, then it acts. Plan mode is on by default — nothing touches your working tree until you approve it.
flowchart TD
I["You type an instruction"]
R["It reads first\nsearches patterns, reads files — no writes yet"]
P["It proposes a plan\nnumbered steps, nothing written"]
G{"You approve?"}
A["It acts\nedits files, runs commands, streams every diff"]
E["You edit the plan\nor tell it what to change"]
I --> R --> P --> G
G -->|"yes"| A
G -->|"no / edit"| E
E --> P
A -->|"result"| I
classDef step fill:#1b3281,stroke:#0f1f52,color:#ffffff
classDef gate fill:#f27b21,stroke:#c25d10,color:#ffffff
class I,R,P,A,E step
class G gate
--always-approve exists precisely because approval is the default, not the
exception.
| Use it | Install · Connect a model · Run · What it can do |
| Configure | All model providers · Configuration reference · User guide |
| Build | Build from source · Develop |
| Enterprise | AiNxt gateway · Four products |
The CLI speaks three wire protocols. Pick the right api_backend and any
provider works:
| Provider | api_backend |
Auth |
|---|---|---|
| Anthropic (Claude) | messages |
env_key + anthropic-version header |
| OpenAI (GPT) | responses |
env_key = "OPENAI_API_KEY" |
| Ollama (local) | chat_completions |
AINXT_API_KEY=local placeholder |
| vLLM / LiteLLM / llama.cpp | chat_completions |
env_key or api_key |
| Together AI / Groq / OpenRouter | chat_completions |
env_key |
Not supported natively: Azure OpenAI (needs
api-versionquery param), AWS Bedrock (SigV4 auth), Google Vertex AI (service-account auth). Put an OpenAI-compatible proxy in front of those.
More examples — Together AI, capability overrides, sampling params:
docs/user-guide/11-custom-models.md.
CLI flags → Environment variables → ~/.ainxt/config.toml → defaults
| File | Purpose |
|---|---|
~/.ainxt/config.toml |
Models, UI preferences, MCP servers, features |
env.example |
Every env var documented with defaults |
Useful env vars:
export AINXT_MAX_RETRIES=2 # retry budget (default 15 ≈ 6 min — set lower in CI)
export AINXT_ALLOW_INSECURE=1 # allow http:// endpoints (dev only)
export RUST_LOG=ainxt_shell=debug # verbose loggingFull reference: env.example ·
docs/user-guide/05-configuration.md
If your organisation runs AiNxt Enterprise, point the CLI at it for governed access, shared budgets, audit and model governance. This is optional — the CLI works standalone without it.
export AINXT_GATEWAY_URL=https://your-gateway.example.com
ainxt login # saves token to ~/.ainxt/credentials.json
ainxtDo not mix gateway and direct-provider config.
AINXT_GATEWAY_URLhas/ainxt/v1/apiappended automatically — pointing it atapi.anthropic.comwill 404 every call. Use[model.*]entries inconfig.tomlfor direct providers instead.
Organisation-specific env files (gateway URL, endpoints) are not in this repo —
env.example documents every variable so any organisation can produce its own.
Just want to use the CLI? The curl command above is all you need — no build required. This section is for contributors, auditors, or anyone who wants to run an unreleased commit.
git clone https://github.com/npci/ainxt-cli.git
cd ainxt-cli
./setup.sh # checks prereqs, offers to install them, builds ainxt./setup.sh is inside the cloned repo — run it from the ainxt-cli/ directory.
./setup.sh --check inspects prerequisites without changing anything.
./setup.sh --release builds the optimised binary.
What you need: Rust (auto-installed by setup.sh), protoc (DotSlash on
Unix, winget install Google.Protobuf on Windows), ~10 GB disk for target/.
# Or build directly once prereqs are in place:
cargo build -p ainxt-pager-bin --bin ainxt # debug
cargo build --profile release-dist -p ainxt-pager-bin --bin ainxt # release
./target/debug/ainxt --versionFull prerequisites detail: § Prerequisites.
| Tool | Why | Check |
|---|---|---|
| Rust | Builds everything. Version pinned by rust-toolchain.toml, fetched automatically. |
cargo --version |
| protoc | Compiles API definitions. Unix: DotSlash runs the hermetic pinned version. Windows: winget install Google.Protobuf. |
dotslash --help or protoc --version |
| Visual Studio Build Tools (Windows only) | MSVC linker. winget install Microsoft.VisualStudio.BuildTools with the "Desktop development with C++" workload. |
rustc -vV shows host: ...-msvc |
| ~10 GB disk | target/ after a debug build. |
df -h . |
# Check it compiles (fastest — no binary produced)
cargo check -p ainxt-pager-bin
# Run tests — no gateway or model needed, uses a built-in mock server
cargo test -p ainxt-sampler
cargo test --workspace # all ~80 crates (slow)
# Lint and format
cargo clippy -p ainxt-pager-bin -- -D warnings
cargo fmt
# Build and run
cargo build -p ainxt-pager-bin --bin ainxt
./target/debug/ainxt| Path | What it is |
|---|---|
crates/codegen/ainxt-pager-bin/ |
Entry point — main.rs, CLI args, startup |
crates/codegen/ainxt-pager/ |
TUI — scrollback, prompt, modals, slash commands |
crates/codegen/ainxt-shell/ |
Agent runtime — session loop, tool dispatch, auth |
crates/codegen/ainxt-sampler/ |
LLM HTTP client — streaming, API backends, auth headers |
crates/codegen/ainxt-tools/ |
Tool implementations — bash, file edit, grep, web fetch |
crates/codegen/ainxt-workspace/ |
Filesystem — VCS, permissions, sandbox, checkpoints |
crates/codegen/ainxt-config/ |
Config loading — config.toml, managed config |
crates/codegen/ainxt-env/ |
Env constants — all env-overridable |
crates/codegen/ainxt-mcp/ |
MCP — Model Context Protocol server integration |
| I want to change… | Look in |
|---|---|
| CLI flags | crates/codegen/ainxt-pager/src/app/cli.rs |
| A slash command | crates/codegen/ainxt-pager/src/slash/commands/ |
| A built-in tool | crates/codegen/ainxt-tools/src/implementations/ |
| Model API calls | crates/codegen/ainxt-sampler/src/client.rs |
| Auth / login | crates/codegen/ainxt-shell/src/auth/ |
See CONTRIBUTING.md for PR process, DCO sign-off and code style.
The full guide ships inside the binary and is readable as Markdown:
| Chapter | |
|---|---|
| Getting started | Custom models |
| Keyboard shortcuts | Headless / CI mode |
| Slash commands | Agent mode |
| Configuration | Sandbox |
| MCP servers | Permissions & safety |
| Skills | Plan mode |
Also at the repo root: INSTALL.md · RUN.md ·
CONFIG.md · env.example · SECURITY.md
Upstream documentation (Grok Build fork)
AiNxt CLI is a fork of Grok Build by SpaceXAI / xAI. Most behaviour is upstream behaviour, so upstream's docs are the authoritative reference for anything AiNxt did not change:
| Resource | Use it for |
|---|---|
| docs.x.ai/build/overview | Full online docs — concepts, tools, MCP, skills, sandboxing |
| Upstream user guide | 27-chapter source this guide is derived from |
26-config-reference.md |
Exhaustive config reference (not carried into this fork) |
Translate as you read: upstream uses the grok binary with XAI_* / GROK_*
env vars and ~/.grok/. Here it is ainxt, AINXT_*, and ~/.ainxt/. Where
the two disagree on gateway, auth, model catalogue or TLS — this repo is correct.
AiNxt is four products on a shared foundation. This repository is AiNxt CLI.
| Product | What it provides | |
|---|---|---|
| 01 | AiNxt Enterprise | Governed enterprise AI — web, desktop, Office add-ins |
| 02 | AiNxt OS | Foundation for building AI applications and agents |
| 03 | AiNxt Code | AI inside the editor — complete, rewrite, explain, fix |
| 04 | AiNxt CLI ← this repo | AI in the terminal — ask, build, fix, automate, execute |
The CLI is not a satellite of Enterprise. It runs standalone. AiNxt Code embeds this CLI as its agent engine.
This software uses cryptography via standard open-source libraries. Laws on import, possession, use and re-export of encryption software differ between countries — check what applies where you are.
First-party code: Apache-2.0 — LICENSE · NOTICE
(fork attribution: derived from SpaceXAI "Grok Build", Apache-2.0).
Third-party: THIRD-PARTY-NOTICES ·
crates/codegen/ainxt-tools/THIRD_PARTY_NOTICES.md
This project is a fork of Grok Build by
SpaceXAI. This fork adds bearer-token sign-in against a self-hosted gateway,
a gateway-sourced model catalogue, and replaced default endpoints — full record in
NOTICE as Apache-2.0 §4(b) requires.
"Grok", "xAI" and "SpaceXAI" are trademarks of their respective owners. AiNxt CLI is not affiliated with, endorsed by, or supported by xAI or SpaceXAI.
Also includes tool implementations from
openai/codex (Apache-2.0) — see
crates/codegen/ainxt-tools/THIRD_PARTY_NOTICES.md.
Licensed under the Apache License, Version 2.0. http://www.apache.org/licenses/LICENSE-2.0
Distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND — see the licence for the specific language governing permissions and limitations (§7 Disclaimer of Warranty, §8 Limitation of Liability).