@getoatmilk/cli

中文文档
0.3.72发布于 2026/11/13AGPL-3.0-onlyES Module零依赖近 30 天下载 6375

Oatmilk in your terminal: browse and act on your company's books, and talk to Ask AI, interactively or headless.

原始使用文档
文档目录15 节
  1. Install
  2. First run
  3. Memory and provider keys
  4. Send email
  5. Sign in
  6. Ask AI on your own model
  7. Log hours as a contractor
  8. Ask someone for missing details
  9. Add receipts and connect your data
  10. The app
  11. Your data
  12. Headless
  13. MCP
  14. Options
  15. License

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.

ChoiceWhat it does
Sign in to OatmilkUse 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 accountNew 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 computerNo 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 optionsChoose 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 ↑↓ 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.

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>.

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

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
--localUse the Oatmilk on this computer, starting it if it's stopped.
--cloudUse Oatmilk Cloud.
--offline, OATMILK_OFFLINE=1Refuse any Oatmilk on the internet: only this computer and its network. No update checks either.
--setup, --no-setupShow the first-run setup again, or never.
--no-startDon't start a stopped local Oatmilk.
--no-aiThe app without Ask AI; exec refuses to run.
--theme, OATMILK_THEMEThe app's theme: system, or one like matcha. /theme saves one.
OATMILK_TERMINALlight or dark, if the app misreads your terminal's background.
OATMILK_NO_UPDATE=1Never check for new versions (CI never checks).
OLLAMA_HOST, LMSTUDIO_URLWhere to look for Ollama and LM Studio.
OATMILK_DATA_DIRWhere the CLI keeps a downloaded copy of Oatmilk's source and the dev server's log.
--host, OATMILK_HOSTThe Oatmilk address. Default https://app.getoatmilk.com; staging works, and so does your own Oatmilk, such as https://oatmilk.localhost.
--org, OATMILK_ORGThe company to work in.
OATMILK_API_KEYSign in with an API key.
OATMILK_TOKENSign in with an OAuth access token.
OATMILK_CONFIG_DIRWhere sign-ins are saved.
OATMILK_NO_BROWSER=1Never open a browser.
NO_COLORPlain output.
NODE_EXTRA_CA_CERTSFor 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.

版本与发布记录

@getoatmilk/cli 共发布 71 个版本,首次发布于 2026/10/06;过去 12 个月发布了 71 个版本。

版本发布日期距今
0.3.72latest2026/11/133 天前
0.3.712026/11/115 天前
0.3.702026/11/115 天前
0.3.692026/11/115 天前
0.3.682026/11/115 天前
0.3.672026/11/078 天前

关于 @getoatmilk/cli 的常见问题

@getoatmilk/cli 是什么?

Oatmilk in your terminal: browse and act on your company's books, and talk to Ask AI, interactively or headless.

如何安装 @getoatmilk/cli?

在项目目录运行 npm install @getoatmilk/cli,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 oatmilk,可以用 npx oatmilk 直接运行。

@getoatmilk/cli 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/getoatmilk__cli 是否存在。

@getoatmilk/cli 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@getoatmilk/cli 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=22。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@getoatmilk/cli 可以商用吗?

@getoatmilk/cli 使用 AGPL-3.0-only 许可。最严格的 Copyleft:除分发外,通过网络向用户提供基于它的服务也需要开源对应源码。闭源 SaaS 使用前务必评估。以上为概括,不构成法律意见,请以许可原文为准。

@getoatmilk/cli 的下载量有多少?

根据 npm 官方下载统计,@getoatmilk/cli 在 2026/10/17 – 2026/11/15 这 30 天内被下载 6,375 次,日均约 213 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@getoatmilk/cli 还在维护吗?

最新版本 0.3.72 发布于 2026/11/13(3 天前);至今共发布 71 个版本,其中过去 12 个月发布了 71 个;首次发布于 2026/10/06。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。