Docs

Omi CLI

An AI coding agent for your terminal. It works in the folder you start it in, on your computer, and asks before it changes anything.

Install

You need Node.js 18.17 or newer. Omi CLI has no other dependencies. Install it once:

terminal
npm install -g @builditomi/cli

Or run it without installing, or with the install script (it checks Node and runs the same npm install):

terminal
npx @builditomi/cli
curl -fsSL https://cli.builditomi.com/install.sh | sh

Update by running the same install command again. Remove with npm uninstall -g @builditomi/cli and delete ~/.omi.

Sign in

Omi CLI uses your BuildItOmi account (the same one as the App, Bolts and the API; its credits are separate). Run:

terminal
omi login

It shows an 8-letter code and opens cli.builditomi.com/device. Sign in or create a free account, check the code matches, and approve. The terminal signs in by itself. Each computer gets its own sign-in, which you can sign out on your account page. omi whoami shows who you are and your credits; omi logout signs this computer out.

Your first task

Open a project and start Omi. In a git repository it works from the repository root.

terminal
cd my-project
omi
› add input validation to the signup form and a test for it

Or give the task straight away: omi "why does the build fail?". Omi reads the code it needs, shows a plan for bigger jobs, proposes each edit as a diff, runs your tests, and ends with a short summary and the credits it used. Press esc or ctrl+c to stop it mid-task; end a line with \ to type more lines.

Approvals and modes

Every edit shows a coloured diff. Answer y to apply, n to refuse, a to allow all edits for the rest of the session, or type what you want instead; Omi reads your answer and adapts. Commands work the same way; a allows that command for the session.

ask (default)Asks before every edit and every command that isn't read-only.
auto-editApplies edits without asking (you still see each diff); asks before commands. Start with omi --auto-edit.
yoloRuns everything without asking. Use it in a container or a clean git tree. Start with omi --yes.
planReads and plans only; refuses every change. Start with omi --plan.

File tools only work inside the project folder. /undo reverts the last task's file changes, with or without git.

Plan, then build

For bigger changes, ask for a plan first. Omi investigates and writes a numbered plan without touching anything. Read it, ask for changes, then build:

terminal
› /plan move the auth code from callbacks to async/await
  … (Omi reads, then shows a plan)
› /build

Tests and the fix loop

/test finds the project's test command (from package.json, pyproject.toml, Cargo.toml, go.mod, Maven, Gradle or a Gemfile), allows it for the session, runs it, and fixes failing code until the tests pass or it is sure a failure can't be fixed in the project. It changes a test only when the test itself is wrong, and tells you when it did. Give your own command with /test npm run test:unit.

Git

Each turn Omi knows the branch, uncommitted files and recent commits. It never commits, pushes or switches branches unless you ask. /diff shows what changed; /branch fix-login creates a branch; /commit writes a message in your repository's style from the staged diff, which you approve or replace.

Sessions

Every conversation is saved to ~/.omi/sessions after each step, with the plan and the file checkpoints that /undo uses.

terminal
omi --continue        # the last session in this project
omi --resume          # list this project's sessions
omi --resume 20261120-a1b2c3

Long sessions keep only the start of old tool output, so each turn stays fast and cheap. /compact summarises the whole conversation when you want a clean slate with the context kept; Omi also does this by itself when a session gets very long.

Project memory

OMI.md at the project root is read at the start of every turn: build, test and lint commands, conventions, things to avoid. /init writes it for you after exploring the project; /memory always use pnpm adds a line; Omi adds notes with its remember tool when it learns something lasting. An AGENTS.md is read too, and ~/.omi/OMI.md holds your own preferences for every project. Commit OMI.md so your team shares it.

Files and images

Mention a file with @path and it is attached to your message in full; @folder/ attaches the folder's file list. Screenshots and other images (PNG, JPG, WebP, GIF, up to 5 MB) attach the same way and Omi can see them. Press Tab after @ to complete a path, or after / to complete a command.

omi
› why does @src/cart.js round wrong? the bug report: @docs/bug-42.md
› make the header match @design/header.png

Slash commands

Every command and option.
Plan mode: Omi reads, searches and writes a plan, and changes nothing.
Back to build mode. Right after /plan, it applies the plan.
Runs your tests and fixes failures until they pass. Finds the command itself (npm test, pytest, cargo test, go test …) when you don't give one.
What changed: git diff against HEAD, or the session's own changes outside git.
Writes a commit message from the staged diff (offers to stage everything first); you approve or type your own.
Shows the branch, or creates and switches to a new one.
Puts back every file the last task changed (new files are removed).
Switches the model. Remembered for next time.
Switches how much Omi asks before acting.
Deeper thinking for hard problems (slower, more credits).
Explores the project and writes OMI.md, the project memory.
Shows OMI.md, or adds a note to it.
Summarises a long conversation so the next turns are faster and cheaper.
Starts a new session (the old one stays saved).
Lists this project's sessions · opens one.
The MCP servers running and their tools.
Plan and credits left · credits this session used.
Sign in, sign out, leave (ctrl+c twice also leaves).

What the agent can do

These tools run on your computer. Omi can call several in one turn when they don't depend on each other.

list_files, globSee the project's files (respects .gitignore) and find files by pattern.
grepSearch contents with a regular expression (uses ripgrep if installed).
read_fileRead a file, or part of a big one, with line numbers.
edit_file, write_file, delete_fileChange files. You see a diff and approve each one (unless auto-edit or yolo).
run_commandRun a shell command in the project root. Read-only commands (ls, cat, git status, git diff …) run without asking; anything else asks.
exploreSend a research question to a helper agent that reads the code by itself and reports back with file:line references. Several run at once.
web_fetchRead a web page or link (docs, a GitHub file) as text. Asks for each new site unless you allow it.
web_searchSearch the web and get an answer with source links. Costs about two or three turns of credits, so it asks first in the default mode.
mcp__server__toolTools from your MCP servers. Each call asks first unless you allow it.
update_planShow its plan and tick off steps as it goes.
ask_userAsk you a question when it truly needs a decision.
rememberSave a lasting fact to OMI.md.

MCP servers

Omi CLI connects to MCP (Model Context Protocol) servers that run on your computer over stdio: issue trackers, databases, browsers, internal tools. Their tools appear to the agent as mcp__server__tool, and every call asks first unless you allow it. Servers are saved in ~/.omi/mcp.json in the usual mcpServers format, so a config from another agent works as it is.

terminal
omi mcp add github GITHUB_TOKEN=ghp_… -- npx -y @modelcontextprotocol/server-github
omi mcp list
omi mcp remove github

Allow a server's tools without prompts in a script with --allow-tool "mcp__github__*". An MCP server runs with your permissions: add only servers you trust.

Models and credits

fastQuick questions, small edits, lowest cost.
standard (default)The default: the model that writes BuildItOmi's own app code.
maxHard refactors and debugging; about 2.7 times the cost of Standard. On paid plans.

If the model you chose is overloaded at Google, one backup model answers that turn and Omi says so; you are charged what the backup really cost. Every agent turn is charged the tokens it really used, at the model's price, in credits. Tokens the model reuses from earlier in the same session cost less. After each task Omi shows what it used and what is left; /cost shows the session total and omi usage your plan. Every account gets 1,00,00,000 free credits each month; see pricing for plans and packs. When credits run out Omi stops and tells you; nothing is charged for a turn that fails.

Scripts and CI

-p runs one task, prints the answer and exits. Without --yes it refuses changes when no one is there to approve them. Pipe text in as context:

terminal
omi -p "summarise what this repo does"
npm test 2>&1 | omi -p --auto-edit --allow "npm test" "fix these failures"
omi -p --output-format json "list the TODOs in src/" > todos.json
OMI_TOKEN=omi_… omi -p --yes -m fast "update the changelog for this diff"

--allow "npm test" lets exactly that command (and ones starting with its first two words) run without asking; --allow-tool does the same for web_fetch, web_search or MCP tools. --output-format json prints one JSON object: result, filesChanged, credits, creditsLeft and sessionId.

For CI, sign in once on your computer and copy the token from ~/.omi/credentials.json into a secret named OMI_TOKEN. It spends your account's credits; sign it out on the account page if it leaks.

Files and settings

~/.omi/credentials.jsonYour sign-in token (only readable by you).
~/.omi/config.jsonYour default model.
~/.omi/mcp.jsonYour MCP servers.
~/.omi/OMI.mdYour own preferences, read in every project.
omi updateInstalls the newest version (Omi also tells you once a day when one is out).
~/.omi/sessions/Saved sessions.
OMI_HOMEKeep all of the above somewhere else.
OMI_TOKENSign in without omi login (scripts and CI).
OMI_NO_BROWSER=1Don't open the browser on login (print the link only).
NO_COLOR=1Plain output without colours.

Privacy and safety

The files Omi reads, the command output it sees and your messages are sent to our service only to run the model for that turn. We keep token counts and credits for billing; we don't store your code or conversations, and we don't train models on them. Sessions are saved only on your computer. Omi refuses file paths outside the project, asks before changes in the default mode, and is told never to print secrets from .env files. Commands you approve run with your permissions, so read them before you say yes.

Troubleshooting

omi: command not foundnpm's global folder isn't on your PATH. Run npm config get prefix and add its bin folder to PATH, or use npx @builditomi/cli.
Needs Node.js 18.17Install a current Node.js from nodejs.org (or with nvm).
Browser didn't open on loginOpen cli.builditomi.com/device yourself and type the code.
"Your credits are used"Add a pack or choose a plan on the pricing page; the next turn works at once.
"Omi is very busy"The model was overloaded for a moment; Omi retries by itself. Nothing is charged for a failed turn.
Something elseAsk at help.builditomi.com.