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.
Memory and provider keys
Memory and dreaming live in Settings too. Press Ctrl+K and search for memory or dream, or run
oatmilk settings memory setup. Workspace facts and your own private memory stay separate; the same screen sets
the dream cadence and retention and shows run results. Use settings memory show|list|status|dream for headless
work, adding --for personal for your own memory.
Search for Anthropic or AI keys to use your workspace's provider credits. oatmilk settings keys save anthropic
takes a hidden prompt or a key piped on stdin. It requires your own administrator sign-in, checks the key and stores
it encrypted for this workspace. settings keys show shows status and key hints; settings keys remove anthropic
removes it. Never put a provider key in command-line arguments or an AI prompt.
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.
Use /permissions to choose Ask for approval or Bypass approvals (YOLO). The choice stays on this computer for
your signed-in account and workspace, including when using a local model. oatmilk settings permissions ask or
oatmilk settings permissions bypass changes that saved choice. Scripts can override it for one request with
oatmilk exec --permission-mode bypass "…" or --permission-mode ask. Your role and the server's checks still apply.
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
oatmilk hours payment # your saved payment methods
oatmilk hours payment select <id> # choose your default from the saved methods
Running oatmilk opens your hours, a logs time one question at a time, and p chooses your default payment method.
Finance and admins can choose it from a contractor's row with p, or use oatmilk pay methods --contractor <id>
and oatmilk pay method <method-id> --contractor <id>. Changing the default does not send money.
Ask someone for missing details
Open a supported record in the terminal and press q to ask someone who can access it. Choose the person, the exact
form, and what they need to add or check. Their task is saved immediately; the result says when its notification is
waiting or queued. Neither state proves the email reached their inbox. Home's Your requests opens the task list,
where t opens the exact task, d completes it, and x cancels an open request through the same permission checks.
oatmilk requests # your open tasks
oatmilk requests people contractor <id> # eligible people and the known owner
oatmilk requests create contractor <id> --to owner --focus payment --only-if-missing --note "Add institution and transit numbers so payroll can send your payout" --yes
oatmilk requests show <id> # the request and its exact destination
oatmilk requests done <id> --note "Added the requested details" --yes
oatmilk requests cancel <id> --yes
oatmilk hours requests # your own contractor tasks
oatmilk hours requests done <id> --yes
--focus payment|profile|tax|hours opens that contractor's form; other records use record. Use --only-if-missing
for contractor payment, profile, or tax gaps so resolved details stop the reminder. Oatmilk checks active access,
never accepts an arbitrary recipient or destination, and keeps missing-info requests tied to the same organization.
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↑↓orj 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…);oopens 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 —
Tabmoves between the sidebar, the screen and the message box.⌃Oshows or hides the chat,⌃Gopens a page Ask AI offered,⌃Bgoes 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.
/themetries each one live;⏎keeps it.
Tax preparation has native year-end questions (q), sales tax coverage (s), and accountant work (a). Saved answers,
changed records, original-currency totals, missing CAD amounts and supporting evidence stay visible. Administrators and
finance teammates can answer the company questions and upload PDF or photo originals. Shareholder tax details opens
the selected person's secure number form and checks its saved masked result. Raw numbers never go into terminal forms,
command arguments, Ask AI or MCP tools.
Settings › My tax details shows your optional personal SIN's masked status, company permissions, each named accountant's
access, requests, notices and history. Save your SIN independently of any company. Sharing lists every company with
a verified association, including contractor and team roles; a shareholder record is needed when the chosen filing
requires one. Choose the company, purpose, reporting period, named accountants and end date in the terminal; your own
signed-in account confirms the prepared review. The terminal checks until that review is confirmed,
or shows its failure or expiry. Withdrawal, accountant revocation, voluntary request decline, company cancellation and
delivery status work natively. Saving your number alone gives no company permission. Company-held numbers can remain
on the company's secure form without moving them to a personal account.
Open it directly with oatmilk --page '/account?section=tax-details', including before joining or creating a workspace.
The account screen uses your own sign-in; Ctrl+W opens the normal company workspace selection when you need it.
If a filing needs a missing shareholder person, the terminal keeps the company, purpose and period while an
administrator explicitly reviews an existing record or adds their real details. Other people can ask a selected
verified administrator, track the saved setup task and cancel it. The assigned administrator opens the native task
and saves the actual person in the register. Setup creates no shares or SIN-sharing permission.
Ctrl+A on the account screen opens your personal Ask AI chat, including for contractors and people with no workspace.
v opens a returned private native form in place. That form privately checks the company and person, keeps known
purpose, year and recipients, and shows the exact approval. Company names, people and register details stay out of
the account model. Raw SIN entry stays in the secure browser form. /chats, /new and /retry manage only your
account chats; --no-ai keeps them off. The same account connection is available headless:
oatmilk exec --page '/account?section=tax-details' 'Help me share my tax details for a filing'
oatmilk chats --page '/account?section=tax-details' --json
A company chat opens private tax work with Ctrl+G on its Private tax form offer. The form checks your own
connection separately; its private company information is never returned to that company chat.
An administrator can also add a known person's real shareholder details while requesting their T2 information. The native form explicitly chooses an existing register person or adds real details, preserves ownership records, and notifies the person. Assigned setup tasks use their saved company and current request/register revisions without requiring an active workspace. Setup completion and consent to share remain separate.
Press i in My tax details, or t in Accountant work, for the company's explicitly shared tax details. The native
index shows the exact person, reporting purpose and period, masked status and blockers. c chooses a verified company;
a lets its administrator request details from a known member or contractor without a shareholder record. Requests
retain the selected accountants and delivery state. Full number view and copy use the exact secure browser form.
Accountants connect through OAuth's existing MCP view and comment permissions. With Comments access they can ask a
year-end question, request a category change from a transaction (C), download an answer's evidence and accept or reopen
their own question. Administrators can proactively grant or revoke company tax-number view in Accountant work › Access;
personal account permission remains separate. Full number entry, positive personal sharing consent and number reveal
use the secure signed-in browser review. The CLI displays metadata and masked status only.
Accountants can ask an administrator to classify or reconcile saved records: q on financial statements, financial
checks or Reports; w on one transaction or bank line; W for an exact subset of loaded rows. The terminal previews
the real report line, account, total or check, keeps book and bank totals separate by currency, and lets you choose the
records and verified administrator before sending. The approval also covers the later completion notice.
Open the assigned task from Requests, or press w in Accountant work to open the work queue. The native detail shows
the original and current records, remaining checks and notification delivery state. Administrators use c to classify,
m to match a receipt or create the missing bank record, and a to review the current book record. Matching supports
explicit currency amounts and exchange-rate proof. s explains an already-correct record only when its checks pass;
b returns a source question. Saved record checks decide completion. The requesting accountant reviews all records
before a accepts the work, or r reopens it. x cancels through the work request's own action.
The headless catalog exposes the same supported actions, for example:
oatmilk actions tax.questions.list
oatmilk actions accountant.work.preview
oatmilk actions accountant.work.request
oatmilk api tax.questions.list '{"period":{"kind":"corporate","from":"2025-08-01","to":"2026-07-31"}}'
oatmilk api accountant.comments.list '{}'
oatmilk api personalTax.get '{}'
oatmilk api personalTax.requests.list '{"status":"all"}'
oatmilk api personalTax.notifications.list '{}'
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.