CLI Reference

The pindusagi / indusagi command-line front door. It parses argv, assembles an immutable boot context through an ordered stage pipeline, and dispatches to one of three runners (one-shot print, NDJSON wire, or interactive REPL). The machinery lives in indusagi.shell_app; the console scripts map to indusagi.shell_app.cli:run.

Table of Contents

• Invocation
• Flags
• Modes
• Auth Subcommand
• Environment Variables
• State Directory
• Settings
• Exit Codes
• Public API
• Programmatic Use
• See Also

Invocation

Install the package and both console scripts (indusagi and pindusagi, identical entry points) become available:

pip install indusagi                 # core only
pip install "indusagi[mcp,tui]"      # add MCP server mounting + the Textual TUI

pindusagi [options] [prompt...]

Everything after the option flags is collected into a free-text prompt. A bare -- terminator forces every remaining token to be treated as a positional, even if it looks like a flag. The parser (tokenize_invocation) is pure and table-driven — there are no per-flag branches — and supports long (--name), short (-x), glued (--name=value, -xvalue), clustered (-ip = -i -p), and repeatable forms. A malformed invocation (unknown flag, missing value, unparseable number) is reported to stderr and exits 2.

Flags

Every flag is one declarative row in FLAG_SPECS; the --help text is generated from the same table. Requires Python 3.11+.

export ANTHROPIC_API_KEY="sk-..."

# One-shot: print a single answer and exit
pindusagi -m claude-sonnet-4 -p "summarize the package.json in this repo"

# Wire mode: speak the JSON line protocol over stdio (also --rpc / --wire)
pindusagi -m claude-sonnet-4 --json

# Interactive REPL (the default when attended with no prompt)
pindusagi -m claude-sonnet-4

# Run from elsewhere, override the system prompt, no tools
pindusagi --cwd /repo --system "Be terse." --no-tools -p "what does this do?"

--mcp value grammar

--mcp is repeatable; each occurrence accumulates and attaches one external Model Context Protocol server. The value's shape decides the transport:

• An http(s):// URL connects over SSE; the server id is derived from the URL hostname.
• Anything else is shlex.split into a stdio command (the id is the command's basename).

Server ids are de-duplicated with a numeric suffix against any servers already declared in settings. A faulted server is warned about but never blocks startup. MCP mounting requires the mcp extra.

pindusagi --mcp "python -m my_server --port 0" --mcp https://tools.example.com/sse -p "list tools"

Modes

The launcher derives a single RunnerMode from the parsed flags, the presence of a prompt, and whether the session is attended (both stdin and stdout are TTYs). Precedence, highest first:

The help and version modes short-circuit without ever standing up an agent. For running modes, select_runner scans RUNNERS (OneShotRunner, WireRunner, ReplRunner) and returns the first whose accepts() matches the mode.

from indusagi.shell_app import tokenize_invocation

# Mode derivation in action
assert tokenize_invocation(["--json"]).mode == "wire"
assert tokenize_invocation([], attended=True).mode == "repl"
assert tokenize_invocation([], attended=False).mode == "print"
assert tokenize_invocation(["-p", "hello"]).mode == "print"

• print (OneShotRunner) streams assistant text deltas to stdout, then exits; a faulted run exits 1.
• wire (WireRunner) reads one JSON request per line off a worker thread and emits event/result/error lines, serialized byte-for-byte to a fixed JSON shape (camelCase field names, optional fields omitted not nulled).
• repl (ReplRunner) mounts the Textual interactive surface from ui_bridge when both streams are TTYs (requires the tui extra); without a TTY it falls back to a plain-text line loop behind the InteractiveView seam.

Auth Subcommand

pindusagi auth ... bypasses flag parsing entirely (its words would otherwise be read as a prompt) and dispatches to run_auth_command. It manages OAuth sign-ins for providers that support them; the resulting tokens land in the profile credential store and are never printed.

pindusagi auth status            # what's stored + which API-key env vars are set
pindusagi auth login openai      # browser PKCE flow, paste the code back
pindusagi auth refresh openai    # rotate the access token

This surface is API-key-first for Anthropic: auth login anthropic and auth refresh anthropic just print a pointer at ANTHROPIC_API_KEY and exit 0 — only OAuth-capable providers (currently openai) are advertised. The flow is paste-based: there is no local callback server, so you paste either the bare authorization code or the entire redirect URL (the code= parameter is extracted from the latter). The credential store at ~/.pindusagi/auth.json is byte-compatible with the TypeScript builds' format but lives under this build's own profile directory and is never shared.

Environment Variables

The CLI reads provider API keys through the gateway's SECRET_TABLE (the first present, non-empty variable per provider wins) — see LLM Gateway for the full table. The common ones:

The framework reads every branded variable through a single env registry — subsystems never probe os.environ directly. Branded names are composed as INDUSAGI_<SUFFIX> (so env_name("home") yields INDUSAGI_HOME).

State Directory

All per-user state lives under the profile directory, resolved by the Locator. The default is ~/.pindusagi (override with INDUSAGI_HOME):

from indusagi.shell_app import Locator, BRAND

loc = Locator()
print(BRAND.bin_name)          # 'indusagi'
print(loc.settings_path())     # ~/.pindusagi/settings.json
print(loc.auth_store_path())   # ~/.pindusagi/auth.json

Settings

Settings merge from three layers, lowest precedence first: built-in DEFAULT_SETTINGS (collection coding), the global profile file, then the per-project file (later wins). A missing, unreadable, or malformed file contributes nothing rather than raising. On-disk JSON keys stay camelCase:

Model selection (resolve_model_id) layers the -m override over settings.default_model over the hard-coded claude-sonnet-4 fallback; each candidate is validated against the catalog via get_card, so an unknown id is skipped rather than honored.

import asyncio
from indusagi.shell_app import Locator, load_settings, resolve_model_id

loc = Locator()
settings = asyncio.run(load_settings(loc, "."))
print(resolve_model_id(settings, invocation_model="claude-sonnet-4"))

Exit Codes

main() never calls sys.exit — it returns the code. Only the run() console-script shim maps it onto the process and translates KeyboardInterrupt to 130. A finally always runs the boot context's closables in reverse registration order (suppressing Exception, never CancelledError) so MCP fleets and other resources close cleanly.

Public API

indusagi.shell_app re-exports the entry points; indusagi.shell is an alias of the same package.

Programmatic Use

The whole CLI is callable in-process — useful for embedding or testing without spawning a subprocess.

import asyncio
from indusagi.shell_app import main

# Equivalent to: pindusagi --print "explain this repo"
exit_code = asyncio.run(main(["--print", "explain", "this", "repo"]))
print("exited with", exit_code)

Assemble a boot context and select a runner by hand, running the teardown closables yourself:

import asyncio, sys
from indusagi.shell_app import (
    tokenize_invocation, build_boot_context, CliStreams, select_runner,
)

async def drive():
    inv = tokenize_invocation(["--print", "hi"], attended=False)
    ctx = await build_boot_context(
        inv, CliStreams(input=sys.stdin, output=sys.stdout, error=sys.stderr)
    )
    try:
        runner = select_runner(inv)        # OneShotRunner accepts mode 'print'
        return await runner.run(ctx)
    finally:
        for close in reversed(list(ctx.closables)):
            await close()

asyncio.run(drive())

Run the auth status subcommand with a scripted AuthIO:

import asyncio
from indusagi.shell_app import run_auth_command

class CaptureIO:
    def __init__(self): self.lines = []
    def print(self, line): self.lines.append(line)
    def warn(self, line): self.lines.append("WARN: " + line)
    async def ask(self, prompt): return ""

io = CaptureIO()
code = asyncio.run(run_auth_command(["status"], io))
print(code, io.lines)

See Also

• Shell App — the full architecture of the command-line front door.
• Runtime — the agent the runners drive.
• LLM Gateway — model cards, the SECRET_TABLE, and OAuth helpers.
• Interop — MCP server mounting behind --mcp.
• UI Bridge — the Textual interactive surface mounted in repl mode.
• Getting Started — install and first run.
• Package Exports — the full public surface.