@getoatmilk/cli 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,229 @@
-# Temporary Holding Version
+# Oatmilk CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+```sh
+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.
+
+## First run
+
+The first time you run `oatmilk`, it asks one question: how you want to use Oatmilk.
+
+| Choice | What it does |
+| --- | --- |
+| **Sign in to Oatmilk** | Your account at getoatmilk.com, 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. |
+| **Keep everything on this computer** | Your account, books, files and every model here, with no sign-up. Needs Docker; the first start takes about 10 minutes. |
+| **More options** | Choose for each part (sign-in, books, files, Ask AI and agents, classifiers, reading documents, email, web research: here, in the cloud, 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).
+
+```sh
+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
+```
+
+Running it locally needs Docker and [Bun](https://bun.sh), and Oatmilk's source: setup uses the checkout you're in, 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.
+
+## Sign in
+
+```sh
+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 Settings › Developer (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`.
+
+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.
+
+```sh
+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
+
+```sh
+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
+
+```sh
+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
+
+```sh
+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.
+
+```sh
+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:
+
+```sh
+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. |
+| `--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.