Oatmilk CLI

Oatmilk in your terminal. Browse and act on your company's books in a full-screen app, talk to Ask AI, or script everything headless — with your own permissions, in the company you choose.

npx @getoatmilk/cli

Install

Requires Node.js 22 or newer.

curl -fsSL https://getoatmilk.com/install.sh | sh   # macOS and Linux; updates itself
npx @getoatmilk/cli                                  # try it without installing
npm install -g @getoatmilk/cli                       # then run: oatmilk

pnpm add -g @getoatmilk/cli, yarn global add @getoatmilk/cli and bun add -g @getoatmilk/cli work too. Each GitHub release also has standalone binaries for macOS, Linux and Windows that don't need Node.js, with SHA-256 checksums.

oatmilk update installs the newest version the way oatmilk was installed. When one is out, the app shows ↑ 0.3.0 ⌃U at the top right; ⌃U installs it. oatmilk update auto|notify|off chooses whether it updates by itself. The app doesn't look by itself when everything runs on this computer, and never with --offline.

First run

The first time you run oatmilk, it asks one question: how you want to use Oatmilk.

After sign-in, review Models and data for your workspace, one step at a time. People upgrading an already signed-in CLI also see this review. You can choose an existing company, create one, or open a personal workspace. Administrators choose shared AI defaults and the data-placement plan. Each computer keeps its own local model connection. The screen shows Books and AI separately, so local AI with online books is clear.

Press Ctrl+K and search for local, models, offline or setup to find these settings. Use oatmilk settings for a text readout or oatmilk settings setup to review them again. A local-only model choice stops when that model is unavailable; it never falls back to an online model. Chat titles come from the first message without an AI call.

To move existing data, sign in to both installations and run oatmilk migrate plan --to <host> --to-org <id>. The job copies and verifies records and files before cutover, and can resume after an interruption. Changing a setting alone keeps the books where they are. The source copy is retained until you separately close it.

| Choice | What it does | | --- | --- | | Sign in to Oatmilk | Use your Oatmilk account. Nothing to install. When Ollama or LM Studio runs a model that calls tools, it offers to run Ask AI on it, so your questions stay on this computer while your books stay in Oatmilk Cloud. | | Make an Oatmilk account | New here? Make one in your browser, then come back and sign in. You may wait on a short waitlist; the app says so, and r checks again. | | Keep everything on this computer | No account needed. Needs Docker, Bun and Ollama or LM Studio; the first start takes about 10 minutes. Setup checks for them before it asks anything, and ⌃C stops it. | | More options | Choose for each part (sign-in, books, files, Ask AI and agents, classifiers, reading documents, email, web research: here, with your own cloud services, or off), your own cloud services with AI here, or an Oatmilk your team runs. |

Every step shows where you are (2/5), and the setup says how local it is in words (85% local). For the local choices, setup finds Ollama or LM Studio, picks models that fit (a chat model that calls tools and reads images, and a decision model for classifiers when Ollama serves them), downloads missing ones into Ollama, starts Oatmilk in Docker (or from a source checkout with bun run dev), asks your name and your company's name, and signs the terminal in. You never sign in on this computer; the browser gets a password setup shows once (oatmilk local password shows it again).

oatmilk setup                                   # the same screens again
oatmilk setup --local --yes                     # everything here without questions (Ollama or LM Studio running)
oatmilk setup --local --cloud-for agents --yes  # everything here except Ask AI (AI_GATEWAY_API_KEY in the environment)
oatmilk setup --local --models lmstudio --model qwen/qwen3.5-9b --company "Acme" --yes
oatmilk setup --cloud                           # Oatmilk Cloud
oatmilk status                                  # where each part runs, the server, the models, Ask AI, who's signed in
oatmilk local start | stop | restart | logs | open | password | backup
oatmilk models                                  # Ollama and LM Studio here, and what Oatmilk uses
oatmilk models test | pull tev1 | use --models lmstudio --restart
oatmilk models eval                             # are they good enough for Oatmilk's tasks? (a few minutes)
oatmilk models eval --vision-model gemma4:12b --only receipts   # try another model before switching

Running it locally needs Docker and Bun, and Oatmilk's source: setup uses the checkout you're in (or --source <folder>), or downloads one with git. Cloud keys for a mix (Clerk, PostgreSQL, S3, AI Gateway, Resend, Tavily) are asked for in the setup screens, or read from the environment with --yes. They're kept only in the local Oatmilk's own settings file.

Send email

Oatmilk Cloud sends its own email. An Oatmilk you run sends it with Resend: make an API key at resend.com/api-keys and verify the domain you send from at resend.com/domains, then:

oatmilk email use resend --from mail.example.com   # paste the key when asked; it never shows on screen
oatmilk email test [email protected]                  # send a test and wait to see it leave
oatmilk email                                       # who sends it, from where, and the last email
oatmilk email off                                   # stop sending (the saved key goes too)

The key is kept only in that Oatmilk's settings file. On a server set up with bun run self-host setup, run it in the Oatmilk folder there, or pass --source <folder>.

Sign in

oatmilk signup             # no account yet: make one in your browser, then sign in here (or: login --new)
oatmilk login              # opens your browser; approve, then come back to the terminal
oatmilk login --device     # SSH or no browser: sign in on any device, paste back the code
oatmilk login --api-key    # paste an API key from Developers › API keys (or pipe it in)
oatmilk whoami             # who, which company, which permissions
oatmilk orgs use "Contoso" # switch company
oatmilk login --password   # an account on your own Oatmilk, with its email and password
oatmilk logout             # sign out and revoke the token

On an Oatmilk that setup made on this computer, the terminal signs itself in with the account's saved password. oatmilk logout forgets that password too, so you stay signed out until oatmilk login --password.

Oatmilk Cloud may put a new account on a short waitlist. Until you're in, oatmilk login keeps you signed in and says you're on the waitlist (or gives you the form at https://app.getoatmilk.com/join to ask for access), and the app shows the same with r to check again.

Browser sign-in is the same OAuth flow AI apps use for Oatmilk's MCP server: the CLI registers itself once, signs in with PKCE through a one-time redirect to localhost. Your role in each company still decides what you can do. Tokens refresh on their own. They are saved in ~/.config/oatmilk/credentials.json (%APPDATA%\oatmilk on Windows), readable only by you.

An API key belongs to one company and has exactly the permissions chosen when it was made.

Ask AI on your own model

Ask AI in the terminal can think on Ollama, LM Studio or any OpenAI-compatible server on your computer, with your books wherever they are, Oatmilk Cloud included. The model reads them through Oatmilk's tools, signed in as you, and asks before every change. Your questions, its answers and what it reads stay on your computer.

oatmilk ai use ollama      # starts Ollama if needed, downloads a model if it has none, checks it calls tools
oatmilk ai use lmstudio --model qwen/qwen3.5-9b
oatmilk ai                 # where Ask AI thinks, and the models found here
oatmilk ai use oatmilk     # back to Oatmilk's AI
oatmilk -p "What needs me today?" --ai local

In the app, /model switches at once, and the top bar shows the model in use.

Log hours as a contractor

oatmilk hours                                   # this pay period: what's logged, what's not sent, when it's due
oatmilk hours add 2h "Design review"            # also 1h30m, 90m, 1.5 or 1:30; --date yesterday, mon or 2026-10-06
oatmilk hours submit                            # send it for review
oatmilk hours none                              # no work this period
oatmilk hours use "Acme"                        # when you work for more than one company

Running oatmilk opens your hours, and a logs time one question at a time. To log hours by asking Claude or ChatGPT, connect them to https://app.getoatmilk.com/api/mcp?toolset=contractor (oatmilk mcp config prints it).

Add receipts and connect your data

oatmilk add receipt.pdf "lunch photo.jpg"       # like Add a receipt; adding the same file again does nothing
oatmilk connect                                 # receipts by email, Gmail, banks, Wise, Stripe, Notion, Drive
oatmilk connect receipts                        # the address to forward receipts to
oatmilk connect gmail                           # opens the page where you connect it
oatmilk sync                                    # Wise and Stripe, now

Provider keys and sign-ins are entered only in Oatmilk in the browser; the terminal opens the right page.

The app

Run oatmilk (or oatmilk "What needs me today?" to start with a question).

• Sidebar — the same pages as the web workspace for your role: Home, Inbox, Checklist, Transactions, Reimbursements, Invoices, Reports, Agreements, Contractors, Settings, and more.
• Lists — search with /, move with ↑↓ or j k, open with ⏎, switch views with [ ]. The record opens beside the list, with its actions on single keys (approve, categorize, add a note, send, void…); o opens it in the browser. Lists load more as you scroll.
• ⌃K — jump to any page, find transactions, email, invoices and contractors, or run any API action.
• Ask AI — the message box at the bottom is always there. It is the workspace's Ask AI, with the same tools, the screen you're on as context, and the same approvals: it asks before deleting, voiding, granting access or emailing people. Your chats carry over between the terminal and the browser.
• Keys — Tab moves between the sidebar, the screen and the message box. ⌃O shows or hides the chat, ⌃G opens a page Ask AI offered, ⌃B goes back, ? lists every key, and / in the message box lists commands.
• Themes — the same themes as the browser, fitted to a light or dark terminal. /theme tries each one live; ⏎ keeps it.

Your data

oatmilk export                       # every record (a ZIP of each table) and every file, into a folder
oatmilk export --out ~/backup --no-files
oatmilk orgs close                   # close the company for good: offers an export, then asks for its name
oatmilk orgs close --confirm "Acme" --yes
oatmilk wipe                         # remove every sign-in, setting and history from this computer
oatmilk wipe --local-data            # and delete the local Oatmilk's companies, accounts and files
oatmilk local wipe                   # only the local Oatmilk's data

Changing where Oatmilk runs doesn't move the books by themselves, and setup says so. oatmilk local backup saves a local Oatmilk's database and files to restore elsewhere with the same self-host/.env; between Oatmilk Cloud and this computer, oatmilk export --cloud or --local keeps a full copy.

Exporting and closing need an administrator. The web app has the same in Settings › Your data, and the terminal app in Settings (Account and Privacy tabs).

Headless

Everything works without the app, for scripts, CI and other agents.

oatmilk -p "Which receipts am I missing this month?"
oatmilk exec "Categorize the Uber rides as Travel" --yes            # approve changes without asking
oatmilk exec "What changed?" --output-format stream-json             # one JSON event per line
oatmilk exec --continue "And last month?"                             # continue your latest chat
echo "Summarize overdue invoices" | oatmilk exec --output-format json

oatmilk search uber --status needs_you --json
oatmilk api entries.list '{"limit":5}'
oatmilk api invoices.void --input id=… --input expectedRevision=2 --input reason="Sent twice" --yes
oatmilk actions invoice          # find actions; `oatmilk actions invoices.void` explains one

In CI, set OATMILK_API_KEY (and OATMILK_ORG for OAuth tokens with several companies) instead of signing in.

exec exits with 7 when Ask AI needs an answer or an approval it couldn't get; the JSON result lists what it is waiting on. Run it again with --yes to approve, or continue the chat with --chat <id>.

| Exit | Meaning | | --- | --- | | 0 | Done | | 1 | Failed | | 2 | Wrong usage | | 3 | Sign in needed | | 4 | Not allowed | | 5 | Not found | | 6 | Rate limited | | 7 | Needs your input | | 130 | Cancelled |

MCP

AI apps can use Oatmilk's remote MCP server directly, signing in with OAuth. oatmilk mcp config prints the setup for Claude Code, Codex, Gemini CLI and Cursor. For apps that only start local commands, the CLI is a stdio bridge to the same server, signed in as you:

claude mcp add oatmilk -- npx -y @getoatmilk/cli mcp

Options

| Flag or variable | | | --- | --- | | --local | Use the Oatmilk on this computer, starting it if it's stopped. | | --cloud | Use Oatmilk Cloud. | | --offline, OATMILK_OFFLINE=1 | Refuse any Oatmilk on the internet: only this computer and its network. No update checks either. | | --setup, --no-setup | Show the first-run setup again, or never. | | --no-start | Don't start a stopped local Oatmilk. | | --no-ai | The app without Ask AI; exec refuses to run. | | --theme, OATMILK_THEME | The app's theme: system, or one like matcha. /theme saves one. | | OATMILK_TERMINAL | light or dark, if the app misreads your terminal's background. | | OATMILK_NO_UPDATE=1 | Never check for new versions (CI never checks). | | OLLAMA_HOST, LMSTUDIO_URL | Where to look for Ollama and LM Studio. | | OATMILK_DATA_DIR | Where the CLI keeps a downloaded copy of Oatmilk's source and the dev server's log. | | --host, OATMILK_HOST | The Oatmilk address. Default https://app.getoatmilk.com; staging works, and so does your own Oatmilk, such as https://oatmilk.localhost. | | --org, OATMILK_ORG | The company to work in. | | OATMILK_API_KEY | Sign in with an API key. | | OATMILK_TOKEN | Sign in with an OAuth access token. | | OATMILK_CONFIG_DIR | Where sign-ins are saved. | | OATMILK_NO_BROWSER=1 | Never open a browser. | | NO_COLOR | Plain output. | | NODE_EXTRA_CA_CERTS | For a self-hosted Oatmilk on *.localhost that setup didn't make: the path of its local certificate authority, which bun run self-host cert saves. One setup made is trusted on its own. |

License

AGPL-3.0-only.