# Command reference

> Every oatmilk command, option, environment variable, exit code and file.

Source: https://app.getoatmilk.com/docs/terminal/commands

`oatmilk --help` prints a short version of this page.

## Commands

| Command | Does |
| --- | --- |
| `oatmilk [prompt]` | Opens the full-screen app, and asks Ask AI the prompt if you give one |
| `oatmilk -p "<prompt>"` | Asks Ask AI once without the app; the same as `exec` |
| `oatmilk setup` | Chooses how to use Oatmilk: sign in to Oatmilk Cloud, keep everything on this computer, or a mix, saying how local it is (`85% local`); `--local`, `--cloud` or `--host` without questions |
| `oatmilk status` | Where each part runs and how local, whether the local Oatmilk answers, the models, where Ask AI thinks, and who's signed in |
| `oatmilk local <start\|stop\|restart\|status\|logs\|open\|password\|backup\|wipe>` | The Oatmilk running on this computer; `backup` saves its database and files (Docker) |
| `oatmilk models` | Ollama and LM Studio on this computer and the models Oatmilk uses; `models start`, `models test`, `models pull <name>`, `models use` |
| `oatmilk ai` | Where Ask AI thinks in the terminal; `ai use ollama\|lmstudio` runs it on a model on this computer, `ai use oatmilk` goes back, `ai test` checks the model calls tools |
| `oatmilk login` | Signs in through your browser |
| `oatmilk logout` | Signs out of this machine and revokes the sign-in; a local account's saved password is forgotten too |
| `oatmilk whoami` | Who you're signed in as, the company, your role and permissions |
| `oatmilk orgs` | The companies you can open; `orgs use <name or id>` switches; `orgs close` closes the company for good |
| `oatmilk connect` | Where the company's data comes from: receipts by email, Gmail and Outlook, bank and cards, Wise, Stripe, Notion and Google Drive, each with its next step; `connect <source>` takes it |
| `oatmilk sync` | Syncs Wise and Stripe now; `sync wise` or `sync stripe` syncs one |
| `oatmilk export` | Downloads every record and file of the company into a folder |
| `oatmilk wipe` | Removes every sign-in, setting and history from this computer |
| `oatmilk update` | Installs the newest version; `--check` only says whether there is one; `update auto\|notify\|off` chooses whether the app updates by itself |
| `oatmilk hours` | A contractor's pay period; `hours add <time> "<what you did>"` logs time, `hours submit` sends it for review, `hours none` says there were no hours, `hours list`, `hours companies`, `hours use <company>`, `hours open` |
| `oatmilk add <files…>` | Adds receipts, invoices and saved emails (PDF, photos, `.eml`), like Add a receipt; adding the same file again does nothing |
| `oatmilk exec "<prompt>"` | One Ask AI request, streamed to standard output |
| `oatmilk chats` | Your recent Ask AI chats; `chats show <id>` prints one |
| `oatmilk search [words]` | Searches transactions |
| `oatmilk api <action> [input]` | Runs any API action and prints its JSON |
| `oatmilk actions [words or action]` | Lists actions, or explains one |
| `oatmilk mcp` | Serves Oatmilk's MCP tools over standard input and output; `mcp config` prints setup for AI apps |
| `oatmilk help`, `oatmilk version` | The help and the version |

## Options for every command

| Option | Does |
| --- | --- |
| `--host <address>` | The Oatmilk to use. `production` and `getoatmilk.com` mean the hosted Oatmilk; `localhost:3000` a development server. |
| `--org <id>` | The company to work in, for this command |
| `--json`, `-j` | Prints JSON, including errors |
| `--local` | Uses the Oatmilk on this computer, starting it if it's stopped |
| `--cloud` | Uses Oatmilk Cloud |
| `--offline` | Refuses any Oatmilk on the internet: only this computer and its network |
| `--setup`, `--no-setup` | Shows the first-run setup again, or never |
| `--no-start` | Leaves a stopped local Oatmilk stopped |
| `--no-ai` | Opens the app without Ask AI; `exec` refuses to run |
| `--theme <id>` | The app's theme for this run: `system`, or a theme like `matcha` or `marathon` |
| `--debug` | Prints more detail when something fails |
| `--help`, `-h` | The help |
| `--version`, `-v` | The version |

## Options for one command

| Command | Option | Does |
| --- | --- | --- |
| `setup` | `--cloud-for <parts>`, `--off-for <parts>` | Moves parts (`account`, `database`, `files`, `agents`, `classifiers`, `documents`, `email`, `web`) to the cloud, or turns them off |
| `setup` | `--models <server>`, `--model-url <address>` | `ollama`, `lmstudio` or `openai-compatible`, and its address |
| `setup` | `--model`, `--vision-model`, `--classifier-model`, `--embedding-model` | The models to use instead of the ones setup picks |
| `setup` | `--runtime docker\|source`, `--source <folder>` | Runs Oatmilk in Docker or from a source checkout |
| `setup` | `--email`, `--name`, `--company` | Your local account and company |
| `setup` | `--download`, `--pull`, `--yes` | Downloads the source and missing Ollama models without asking |
| `local password` | `--reset` | Sets a new password for your local account |
| `models use` | `--restart` | Restarts the local Oatmilk to use the new models |
| `orgs close` | `--confirm "<name>"`, `--export`, `--no-export` | Closes the company without questions, exporting first or not |
| `export` | `--out <folder>`, `--no-files`, `--force` | Where to save it, without the files, or into a folder that isn't empty |
| `wipe` | `--local-data` | Also deletes the local Oatmilk's companies, accounts and files |
| `connect` | `--no-browser` | Prints the page's address instead of opening it |
| `login` | `--password`, `--email` | Signs in to your own Oatmilk with an account's email and password |
| `login` | `--device` | Signs in on another device, then you paste the code |
| `login` | `--api-key [key]` | Saves an API key; asks for it, or reads it from standard input, when you leave it out |
| `login` | `--no-browser` | Prints the sign-in address instead of opening a browser |
| `login` | `--scopes "<scopes>"` | Asks for fewer permissions than the default, separated by spaces or commas |
| `logout` | `--all` | Signs out of every address |
| `add` | `--for <transaction id>` | Attaches the files to that transaction instead of letting Oatmilk match them |
| `hours add` | `--date <day>` | The day of the work: `today` (the default), `yesterday`, a weekday like `mon`, or a date |
| `hours add`, `hours submit`, `hours none` | `--yes`, `-y` | Keeps the same work twice, or sends without asking |
| `hours list` | `--from <day>`, `--to <day>`, `--limit <n>` | Entries between two days |
| `ai use` | `--model <name>`, `--model-url <address>` | The model to use, and the address of another OpenAI-compatible server |
| `ai use` | `--pull`, `--yes`, `--no-test` | Downloads a missing model into Ollama, uses a model that didn't call a tool in the check, or skips the check |
| `exec` | `--ai oatmilk\|local` | Oatmilk's AI, or the model on this computer, for this request |
| `exec` | `--output-format`, `-o` | `text`, `json` or `stream-json` |
| `exec` | `--yes`, `-y` | Approves steps that delete, void, grant access or email people |
| `exec` | `--continue` | Continues your latest chat |
| `exec` | `--chat <id>` | Continues a particular chat |
| `exec` | `--page <path>` | The workspace page Ask AI should look at, such as `/finance/transactions` |
| `exec` | `--quiet`, `-q` | Leaves out the steps and links on standard error |
| `exec` | `--no-input` | Never asks in the terminal; stops with exit code `7` instead |
| `api` | `--input key=value` | Sets one input field; repeat it for more |
| `api` | `--idempotency-key <key>` | Your own idempotency key for a change |
| `api` | `--compact` | Prints the JSON on one line |
| `api` | `--yes`, `-y` | Runs an action that deletes, voids, grants access or emails people without asking |
| `actions` | `--refresh` | Reads the action list again instead of using the day-old copy |
| `search` | `--status <state>` | `needs_you`, `working`, `done` or `review` |
| `search` | `--limit <n>` | How many to show, up to 500 (default 25) |
| `mcp` | `--toolset <names>` | Only these [toolsets](https://app.getoatmilk.com/docs/mcp.md#choose-what-the-assistant-sees), separated by commas |
| app | `--page <path>` | Opens the app on this page |

`api` takes its input as a JSON object argument, `@file.json`, or `-` for standard input.

## Environment variables

| Variable | Does |
| --- | --- |
| `OATMILK_HOST` | The default address, used when `--host` isn't given |
| `OATMILK_ORG` | The default company |
| `OATMILK_API_KEY` | Signs in with an API key; wins over a saved sign-in |
| `OATMILK_TOKEN` | Signs in with an OAuth access token; wins over a saved sign-in |
| `OATMILK_CONFIG_DIR` | Where sign-ins and settings are saved |
| `OATMILK_CACHE_DIR` | Where the action list is cached |
| `OATMILK_NO_BROWSER` | `1` never opens a browser |
| `OATMILK_DATA_DIR` | Where a downloaded copy of Oatmilk's source and the dev server's log are kept |
| `OATMILK_SOURCE_DIR` | The Oatmilk source checkout that runs the local Oatmilk |
| `OATMILK_OFFLINE` | `1` refuses any Oatmilk on the internet, like `--offline` |
| `OATMILK_SKIP_SETUP` | `1` never shows the first-run setup |
| `OATMILK_THEME` | The app's theme, like `--theme` |
| `OATMILK_TERMINAL` | `light` or `dark`, when the app can't tell your terminal's background |
| `OATMILK_NO_UPDATE` | `1` never checks for new versions |
| `OATMILK_LOCAL_PASSWORD` | The local account's password for `setup --local` and `local password --reset` |
| `OLLAMA_HOST`, `LMSTUDIO_URL` | Where to look for Ollama and LM Studio |
| `NO_COLOR` | Turns colours off |
| `NODE_EXTRA_CA_CERTS` | A certificate authority file to trust, for a self-hosted Oatmilk on `*.localhost` |

## Exit codes

| Code | Means |
| --- | --- |
| 0 | Done |
| 1 | Failed |
| 2 | Wrong usage |
| 3 | Sign-in needed |
| 4 | Not allowed |
| 5 | Not found |
| 6 | Rate limited |
| 7 | Ask AI needs your input or approval (`exec`) |
| 130 | Cancelled |

## Files it keeps

| What | Where |
| --- | --- |
| Sign-ins and settings (`credentials.json`) and message history | `~/.config/oatmilk`, or `$XDG_CONFIG_HOME/oatmilk`; `%APPDATA%\oatmilk` on Windows |
| How Oatmilk runs here (`setup.json`) | Beside the sign-ins |
| A downloaded copy of Oatmilk's source, the dev server's log | `~/.local/share/oatmilk`, or `$XDG_DATA_HOME/oatmilk`; `~/Library/Application Support/oatmilk` on macOS; `%LOCALAPPDATA%\oatmilk\data` on Windows |
| The action list | `~/.cache/oatmilk`, or `$XDG_CACHE_HOME/oatmilk`; `~/Library/Caches/oatmilk` on macOS; `%LOCALAPPDATA%\oatmilk\cache` on Windows |

Sign-ins are written so only your user can read them. Deleting the cache is always safe.