CLI Reference

Synopsis

BharatCode follows the familiar git-style shape: a root command, an optional subcommand, then flags and arguments. Running it bare launches the interactive UI; pass a subcommand to do anything else.

bharatcode                       # launch the interactive TUIbharatcode <subcommand> [flags]  # run a specific commandbharatcode [global flags]        # e.g. --continue, --yolo, --profile

Here is the full set of subcommands at a glance:

bharatcode

With no arguments, bharatcode opens the interactive terminal UI in your current working directory. You talk to the agent in plain language and steer the session with slash commands. Project instructions from AGENTS.md (and CLAUDE.md) are ingested into the system prompt automatically.

$ bharatcode

bharatcode init

Scaffolds a starter configuration file so you have a documented place to set your default model, providers, and options. By default it writes the global config; pass --project to drop a project-local .bharatcode.json in the current repository instead. The Config files page covers every field.

$ bharatcode init            # write the global config$ bharatcode init --project  # write ./.bharatcode.json

bharatcode run

Runs the agent headlessly against a single prompt and exits — the non-interactive counterpart to the TUI. Use it in scripts, CI, Makefiles, or any place you want a one-shot agent run without a terminal UI.

$ bharatcode run "add a unit test for parseConfig"

Flags

• --json — emit machine-readable NDJSON events (one JSON object per line) instead of human-formatted output, so you can stream and parse the run programmatically.
• --output-last-message <file> — write the agent's final message to <file>, which is handy for capturing just the answer from a script.

Emit a stream of NDJSON events to consume the run from another program:

$ bharatcode run --json "summarize the changes in this repo"

Or capture only the final message to a file for use in a later step:

$ bharatcode run "write release notes for v1.2" --output-last-message notes.md

bharatcode login

Authenticates a provider so the agent can call its models. Most providers read their key from an environment variable (for example DEEPSEEK_API_KEY or GROQ_API_KEY); see Providers & Models for how each provider is wired up.

$ bharatcode login

bharatcode logout

Signs out of a provider, clearing stored credentials.

$ bharatcode logout

bharatcode models

Lists the models available from your configured providers — the same catalogue the in-TUI /model picker draws from. Use it to confirm a provider is set up correctly and to find the exact model identifier to reference in your config.

$ bharatcode models

bharatcode sessions

Lists and manages your saved sessions from the command line — the shell-side companion to the TUI's /sessions command. To jump straight back into the most recent session instead of browsing, use the global --continue flag. See Sessions & Fork for how sessions are stored, resumed, and branched.

$ bharatcode sessions

bharatcode revert

Undoes a session's file changes, restoring the files it touched to their pre-session state — an escape hatch when a run went sideways. Pass a session id to target a specific session. By default it refuses to touch files that have changed since the session wrote them; override that with --force, or preview the plan first with --dry-run.

• --dry-run — show what would be reverted without changing any files.
• --force — revert files even if they have changed since the session wrote them.

$ bharatcode revert --dry-run  # preview the restore$ bharatcode revert <session-id>

bharatcode share

Uploads a session transcript to a GitHub gist so you can share a run with a teammate or attach it to an issue. Pass a session id to choose which session to upload. The gist is secret by default; pass --public to publish it publicly instead.

$ bharatcode share              # share the latest session (secret gist)$ bharatcode share <session-id> --public

bharatcode import-history

Imports an existing transcript or prompt list from a file into a new session, so you can carry prior context into BharatCode. The input is parsed as Markdown by default; use --format to select another supported input format.

$ bharatcode import-history transcript.md

bharatcode stats

Reports usage statistics drawn from BharatCode's cost ledger, so you can see how much you have used across sessions. For the spend total against your monthly limit specifically, use bharatcode budget.

$ bharatcode stats

bharatcode budget

Shows the INR-aware cost ledger and your monthly budget. BharatCode tracks spend in rupee terms and gates new work against a monthly limit, and this command is where you check how much of the month's budget remains. The same view is available inside the TUI as /budget.

$ bharatcode budget

bharatcode update-providers

Refreshes the provider and model catalogue. Run it after a provider adds new models so that bharatcode models and the /model picker reflect the latest options.

$ bharatcode update-providers

bharatcode config

Inspects your configuration. BharatCode merges a global ~/.config/bharatcode/config.json with a project-level ./.bharatcode.json, optionally overlaid by a named --profile, and this command helps you confirm what the effective configuration is. The full layering rules, fields, and examples live on the Config files page.

$ bharatcode config

bharatcode doctor

Runs environment and configuration diagnostics — a quick health check you can run when something is not working. It is the first thing to try when a provider, model, or integration is behaving unexpectedly.

$ bharatcode doctor

bharatcode skills

Lists the skills BharatCode discovered in your skill directories — the reusable capabilities the agent can draw on during a run. Use it to confirm a skill is installed and visible before you reference it.

$ bharatcode skills

bharatcode recipes

Lists the recipes discovered for the current project — parameterized, shareable task templates. BharatCode searches the standard recipe directories (your global config directory and the project directory) and prints each recipe's name, title, and description; if none are found, it reports the directories it searched so you know where to add them.

$ bharatcode recipes

bharatcode audit

Inspects the append-only, tamper-evident audit log — the sovereignty feature that records what the agent did, in order, in a form you can verify after the fact. It takes a sub-command:

• bharatcode audit export — export the audit log as JSON Lines (one record per line) for archival or analysis.
• bharatcode audit verify — verify the log's hash chain to detect tampering.

Both sub-commands accept --path to point at a non-default log location; without it, the standard data directory is used.

$ bharatcode audit export > audit.jsonl$ bharatcode audit verify

bharatcode eval

Runs offline benchmark suites against the agent and reports pass/fail metrics — a repeatable way to measure a model or configuration on a fixed task suite. With no flags it runs every suite; the flags below narrow or reshape the run.

• --list — list the available suites without running them.
• --suite <name> — run a specific suite by name (default: all).
• --json — emit newline-delimited JSON, one object per suite, for machine consumption.
• --max-steps <n> — cap agent steps per task (0 uses the harness default of 20).

$ bharatcode eval --list$ bharatcode eval --suite core --json

bharatcode update

Checks whether a newer release is available. With no flags it only reports — nothing is downloaded or changed. Pass --apply to fetch the latest binary, verify its SHA-256 checksum against the published digest, and replace the running binary in place. A checksum mismatch hard-fails the update, leaving the existing binary untouched. The command is a no-op in offline mode and for unstamped builds (e.g. those produced by go install).

$ bharatcode update          # check only$ bharatcode update --apply  # download, verify, and replace

To update automatically on startup, set auto_update: true under options in your config. See Upgrading for the full walkthrough.

bharatcode version

Prints the installed BharatCode version — useful when reporting an issue or confirming an upgrade took effect.

$ bharatcode version

Global options

A few flags apply across the CLI rather than to a single subcommand:

• --continue — resume the latest session. Running bharatcode --continue reopens your most recent conversation instead of starting fresh.
• --profile <name> — overlay a named configuration profile on top of your global and project config, so you can switch between, say, a cheap default and a premium setup.
• --yolo — bypass approval prompts for the run. It is fast but unguarded; see Permissions for the safer approval modes.

Pick up exactly where you left off:

$ bharatcode --continue

Launch the TUI with a named profile applied:

$ bharatcode --profile work