Orlithra Code CLI

orlithra-code is a local autonomous coding agent. It talks to the authenticated /coding backend for model reasoning, then executes deterministic tools on your current workspace: indexing, file edits, patches, safe commands, verification, checkpoints, and undo.

Quick Start

npm install -g orlithra-code
orlithra-code login
orlithra-code
orlithra-code "review this repo and suggest the safest first patch"

Running orlithra-code with no task starts an interactive agent session. It can inspect files, search the workspace, create/edit/delete files under Safe Agent policy, run safe verification commands, persist state, and undo changes. Type follow-up instructions at the You: prompt, use /status, /review, /files, /undo, /apply, and /exit. Passing a task keeps one-shot behavior unless you add --interactive.

If no token is provided, the CLI starts a device login:

Open:
https://orlithra.com/device

Code:
ABCD-1234

Log in through the browser, approve the code, and return to the terminal. This works on Android, Termux, SSH, and headless terminals because it does not depend on a localhost callback. Desktop callback login is still available with --localhost-login for development.

The CLI stores only a short-lived Orlithra CLI session token in ~/.orlithra/code/session.json. Use orlithra-code logout to clear it.

On launch, the CLI checks Orlithra's public CLI manifest and installs the latest hosted CLI tarball when a newer version is available. Use --no-update or ORLITHRA_CODE_NO_UPDATE=1 to skip that check.

Use a local backend during development:

$env:ORLITHRA_API_BASE = "http://127.0.0.1:8080"
npm run orlithra:code -- --mode debug --include backend/src/app.js "why is streaming failing?"

Useful Flags

• --mode plan|generate|debug|refactor|review
• --auto safe|review|full to choose the autonomy policy
• --dry-run to show planned mutations without changing files
• --verify fast|deep to select verification depth
• --cwd <path> to run against another repository
• --device-login to force the Android/Termux-safe device flow
• --localhost-login to use the legacy desktop callback flow
• --include <path> to attach specific file contents
• --max-rounds <n> to allow local tool request loops
• --max-steps <n> and --max-failures <n> to bound autonomous loops
• --interactive to keep a session open after the first answer
• --watch to keep an incremental live watcher open during an interactive session
• --once to exit after one response when launching without a task
• --no-edits to disable file-writing tools
• --yes to approve local tools automatically except shell commands
• --allow-run to permit explicit run_command tool calls; shell commands still ask before running
• --allow-network, --allow-installs, --allow-git-push, --allow-shell for per-session permission grants
• --apply to apply the first generated unified diff after confirmation

Agent State

Each run persists state under .orlithra/code/<sessionId>/:

• state.json
• plan.json
• manifest.json
• failure-memory.json
• tool-log.ndjson
• trace.ndjson
• journal.ndjson
• checkpoints/

Safe Agent mode auto-runs reads, searches, workspace writes, mkdir, patch validation, and safe verification commands. It asks before destructive, install, network, privileged, git push, or shell-like commands.

For automation, use ORLITHRA_AUTH_TOKEN, ORLITHRA_ID_TOKEN, or --token.