Skip to guide

Aditya Code CLI guide

Ask about this guide

Sign in, work safely, resume tasks and watch shared Aditya Code sessions from the developer platform.

Updated 9 sections · Current source build

On this page · 9 sections

Use aditya-code

Aditya is the general model; Aditya Code is the coding agent. The terminal command is aditya-code. The old aroxa alias still works for compatibility, but new commands and scripts should use aditya-code. The CLI talks to the agent runtime for project work and the account service for sign-in. Having a working account does not by itself start or verify that runtime.

This guide describes the implemented commands, not a new installer. Follow your source build’s setup instructions to install the CLI and prepare its runtime. Use aditya-code --help to check the options in the version you installed. Keep credentials, production data and unrelated projects out of a first test workspace.

Choose your project
aditya-code --help
aditya-code --cwd /path/to/project

Sign in through your browser

Run aditya-code login. The terminal prints a browser device-sign-in link and a short code. Open the link, sign in to your account and check that the code, device and request are yours. Approve only a code you started yourself; deny a code sent by someone else. Return to the terminal after approval. The CLI waits for that explicit decision rather than treating browser sign-in as permission to operate on files.

Use whoami to see the signed-in account, plan and balance. Use logout to clear this computer’s sign-in and attempt to end its device session on the server. If the service is unreachable, local sign-out still happens, but server revocation is not confirmed. Never paste access tokens or refresh tokens into a task, screenshot or bug report.

Account commands
aditya-code login
aditya-code whoami
aditya-code logout

Interactive tasks and one-shot work

Start aditya-code without a prompt for an interactive session. For one focused task, pass the prompt as a quoted argument. --cwd selects the project; it defaults to the directory where you launched the command. A workspace path is a scope choice, not a promise that every shell command is isolated from the rest of your computer.

Separate investigation from implementation. Ask for an explanation without code changes first, then authorize a specific patch and a relevant test. Inspect proposed tools and approve only operations that fit your request. Ctrl+C can stop work, but does not establish that completed edits or external actions were rolled back. Review changes and any started process before continuing.

A bounded investigation
aditya-code --cwd "/path/to/my project" "Trace the failing test; do not edit files."

History and durable resume

history lists earlier tasks in the selected workspace. resume [id] continues an earlier session; omitting the id selects the latest. A run id can also identify its session. Resuming restores the recorded conversation, not proof that the project is unchanged or that an earlier observation remains correct. Review the current worktree and environment before requesting the next operation.

The runtime’s records distinguish completed, interrupted and checked work. A reply, a changed file and a passing acceptance check are separate facts. Keep that distinction when reviewing resumed tasks, especially after another person edits the project. Local task records live under .aroxa; that internal folder name remains for compatibility. Do not delete it casually while investigating an incomplete run.

Return to earlier work
aditya-code history
aditya-code resume
aditya-code resume SESSION_ID

Review changes before undoing them

changes lists files the agent wrote in the last task. Use --run to select a specific run. Read the diff alongside the receipt so unrelated edits do not disappear into a broad cleanup. The command reports when a file has changed since the agent wrote it, which matters when you share a worktree or continue editing after a run.

Start undo with --dry-run to see what would change. The undo operation targets journaled file writes and keeps later conflicting edits; it is not a rollback of shell-command side effects, deployments or external services. Inspect conflicts explicitly. A file intentionally preserved because it changed later is not an operation you should bypass with a destructive Git reset.

Review, preview, then undo
aditya-code changes
aditya-code changes --run RUN_ID
aditya-code undo --dry-run
aditya-code undo

Inspect plugins before trusting them

plugins shows workspace-defined MCP servers and skills, including whether they are enabled. These definitions can run programs or connect to services. Read what each plugin does and where its data goes before granting trust. The .aroxa/mcp.json file and .aroxa/skills folder are internal storage locations, not alternative public product names.

trust asks you to review and enable the workspace’s plugins. The approval is pinned to the files shown; changed definitions need review again. untrust turns them off. Trusting a plugin is not blanket authorization for every action it might propose, nor a guarantee that a remote service is safe. Keep task scope and individual execution approvals separate from plugin trust.

Workspace plugin controls
aditya-code plugins
aditya-code trust
aditya-code untrust

Watch a session from the platform

--share is opt-in. Run aditya-code --share on your computer, then open CLI sessions at platform.adityalab.in/cli using the same account. The page replays shared activity and shows a Live badge while the sharing lease is active. It is read-only: it cannot execute commands or approve operations on your computer. Continue the task in your terminal.

Sharing publishes capped user and assistant messages, tool previews, progress and receipt summaries, including changed file names and tokens. It does not publish full file contents, full command output or the full workspace path; nevertheless messages and previews can contain sensitive material. Review what you put in a shared task. Deleting the shared record on the platform does not delete local files or stop the CLI.

  • Platform list: https://platform.adityalab.in/cli
  • Session activity is read-only; approvals stay in your terminal.
Share only when you intend to
aditya-code --share

JSON and non-interactive mode

--json writes one task result with schema aditya-code.task/v1 to standard output. --non-interactive avoids terminal prompts. Both require a prompt for a task run; a process without an interactive terminal also runs headlessly. A task that reaches an approval it cannot receive stops with needs_approval and exit 41 instead of inventing permission.

Read status, verification, steps and the exit code together. A zero exit can accompany an answered question or unverified file changes; it does not mean tests passed. The JSON receipt reports facts collected by the runtime, not an estimated cost or an assumed completion. Do not automatically re-run a needs-approval task with broader permissions simply to make a script continue.

Script-friendly task output
aditya-code --json --cwd /path/to/project "Explain this module; do not edit files."
aditya-code --non-interactive "Inspect the failing test without changing code."

Exit codes and runtime compatibility

Use these exit codes when deciding whether a script can continue. Distinguish account access, a spending limit, an interrupted task and an unavailable runtime rather than treating every nonzero result as the same retryable failure. Preserve the receipt and a redacted error when asking for help; do not substitute a completion claim for a missing check.

The runtime guide still documents internal environment names such as AROXA_PORT and the .aroxa folder. Keep those exact configuration names where required. Their continued existence does not change the public command or brand: use aditya-code for Aditya Code. Check the runtime guide separately when the local agent service cannot be reached.

Aditya Code process exit codes
CodeMeaning
0Done; read the receipt for verification.
1Usage error
3Task failed
10Sign-in required or unavailable
22Budget reached
40Stopped
41Needs approval
99Runtime error
Search covers these 8 guides. Press Esc to close.
Documentation