omi-cli

Русский: быстрый старт · 日本語 README

Talk to Omi from your terminal. Designed for humans and agents.

omi-cli is the command-line interface to the Omi developer API. It exposes scoped, agent-friendly verbs for the four primary nouns Omi maintains about you:

• memories — facts and learnings the system knows about you
• conversations — captured & processed audio/text exchanges
• action items — tasks and follow-ups
• goals — tracked progress metrics

It's intentionally small, scriptable, and JSON-first — everything you need to plug Omi into shell pipelines, CI jobs, agent harnesses, or just your own personal automation.

• PyPI: pypi.org/project/omi-cli
• Docs: docs.omi.me/doc/developer/cli/introduction
• Source: github.com/BasedHardware/omi/tree/main/sdks/python-cli

Install

pipx install omi-cli            # recommended — isolated install
# or
pip install omi-cli

After install, the binary on your $PATH is named omi:

omi --version
omi --help

The PyPI distribution name is omi-cli (the bare omi slot belongs to an unrelated package). The console command is omi regardless.

Quickstart

# 1. Log in. With no flags, omi-cli asks how you want to authenticate:
omi auth login
# → 1) Browser — sign in with Google or Apple (recommended for humans)
# → 2) API key — paste a developer key from app.omi.me (recommended for agents/CI)

# 2. Start using it:
omi memory list
omi conversation list --limit 5
omi action-item list --open
omi goal list

Terminal chat

Sign in with your Omi account, then chat on your current default Omi cloud chat thread:

omi auth login --browser
omi chat                        # interactive; replies stream as they arrive
omi chat "What did we decide?"  # one message, then exit
omi chat --history --limit 20   # recent shared messages
omi chat --clear                 # asks before deleting shared chat history
omi chat --clear --yes           # explicit non-interactive reset
omi --json chat "Summarize today"  # one final response as JSON

Interactive commands: /history, /clear, /tasks, /task add TEXT, /task done ID, /help, and /quit. /clear removes the shared cloud chat history across clients, not just terminal output. It always asks first. The terminal does not keep a second transcript on disk. If a stream disconnects, check omi chat --history before resending because the server may have saved the turn.

This uses the cloud chat backend and its synced memories, conversations, and tasks. It does not grant the terminal live access to the Mac's private screen or the desktop-only agent context; use the desktop app for those. Developer API keys cannot authenticate the user chat endpoint, so omi chat requires browser sign-in. omi ask remains available for scoped, one-shot developer API-key questions.

Pass --json to any command (as a global flag, before the verb) to get machine-readable output, ready for jq, agent harnesses, or whatever else:

omi --json memory list | jq '.[] | {id, content}'

Pretty output displays returned text literally, including square brackets and emoji-like codes such as :warning:. Styling applies to the table layout, not to the contents of your memories or conversations. Tables without predefined columns include fields from every row, in first-seen order.

🇹🇭 คู่มือเริ่มต้นใช้งาน omi-cli (Thai Quickstart)

Looking for localized guides? See the 🇯🇵 日本語クイックスタート (Japanese Quickstart), the 🇮🇩 Panduan mulai cepat (Indonesian Quickstart), the 🇪🇸 Primeros pasos con omi-cli (Spanish Quickstart), the 🇹🇷 Türkçe Hızlı Başlangıç Kılavuzu (Turkish Quickstart), the 🇷🇺 Быстрый старт с omi-cli (Russian Quickstart), the 🇧🇬 Българско ръководство за бърз старт (Bulgarian Quickstart), the 🇲🇳 omi-cli хурдан эхлүүлэх гарын авлага (Mongolian Quickstart), the 🇳🇬 Jagorar farawa cikin sauri ta omi-cli (Hausa Quickstart), the 🇧🇦 Vodič za brzi početak rada s omi-cli (Bosnian Quickstart), the 🇳🇬 Ntuziaka mmalite ngwa ngwa nke omi-cli (Igbo Quickstart), or the 🇪🇹 የ omi-cli ፈጣን መጀመሪያ መመሪያ (Amharic Quickstart). Looking for localized guides? See the nnapulitano (Neapolitan Quickstart), the vosa vakaViti (Fijian Quickstart), the papiamentu (Papiamento Quickstart), the mirandés (Mirandese Quickstart), the hornjoserbšćina (Upper Sorbian Quickstart), the rumantsch (Romansh Quickstart), the armãneashti (Aromanian Quickstart), or the estremeñu (Extremaduran Quickstart).

Looking for localized guides? See the 🇮🇳 मैथिली त्वरित मार्गदर्शिका (Maithili Quickstart), the 🇮🇳 অসমীয়া ক্ষিপ্ৰ আৰম্ভণি নিৰ্দেশিকা (Assamese Quickstart), the 🇧🇩 omi-cli দিয়ে শুরু করা (Bengali Quickstart), or the 🇨🇦 ᐃᓄᒃᑎᑐᑦ (Inuktitut Quickstart).

🇩🇰 På dansk: hurtigstartguide til omi-cli.

Looking for localized guides? See the संस्कृते आरम्भः (Sanskrit Quickstart), or the ᏣᎳᎩ (Cherokee Quickstart). Looking for localized guides? See the asturianu (Asturian Quickstart), the vèneto (Venetian Quickstart), the corsu (Corsican Quickstart), the gagana Samoa (Samoan Quickstart), the lea faka-Tonga (Tongan Quickstart), the ʻōlelo Hawaiʻi (Hawaiian Quickstart), the kalaallisut (Greenlandic Quickstart), the মৈতৈলোন (Meitei Quickstart), the ತುಳು (Tulu Quickstart), the isiNdebele (Ndebele Quickstart), the Kikongo (Kongo Quickstart), or the chisena (Sena Quickstart). Looking for localized guides? See the Kajin M̧ajeļ (Marshallese Quickstart), the Chamoru (Chamorro Quickstart), the Tetun (Tetum Quickstart), the Tok Pisin (Tok Pisin Quickstart), the Aymar aru (Aymara Quickstart), or the Macehuallahtolli (Nahuatl Quickstart).

Looking for localized guides? See the संस्कृते आरम्भः (Sanskrit Quickstart).

Looking for localized guides? See the कोंकणींत सुरवात (Konkani Quickstart). Looking for localized guides? See the 🇭🇰 廣東話上手指南 (Cantonese Quickstart).

Looking for localized guides? See the डोगरी च शुरूआती मार्गदर्शिका (Dogri Quickstart).

Looking for localized guides? See the 🇫🇷 Guide de démarrage rapide en français (French Quickstart), the 🇩🇪 Deutsche Schnellstartanleitung (German Quickstart), the 🇵🇹 Guia de início rápido em português (Portuguese Quickstart), the 🇮🇹 Guida rapida in italiano (Italian Quickstart), or the 🇧🇹 omi-cli དང་འགོ་བཙུགས་ནི། (Dzongkha Quickstart). Looking for localized guides? See the 🇮🇳 हिंदी में शुरुआत (Hindi Quickstart).

Looking for localized guides? See the नेपालीमा सुरुवात (Nepali Quickstart). Looking for localized guides? See the 🇵🇰 سنڌي ۾ omi-cli تڪڙو آغاز (Sindhi Quickstart). Looking for localized guides? See the Sängö (Sango Quickstart), the Qafar af (Afar Quickstart), the Te Ggana Tuuvalu (Tuvaluan Quickstart), the Vagahau Niue (Niuean Quickstart), the Gagana Tokelau (Tokelauan Quickstart), or the Reo Tahiti (Tahitian Quickstart).

Looking for localized guides? See the 🇸🇦 دليل البدء السريع (Arabic Quickstart), the 🇻🇳 Hướng dẫn nhanh (Vietnamese Quickstart), the 🇨🇿 Rychlý start (Czech Quickstart), or the 🇮🇱 מדריך מהיר (Hebrew Quickstart). Looking for localized guides? See the Bislama (Bislama Quickstart), the Sranan Tongo (Sranan Tongo Quickstart), the Karelian (Karelian Quickstart), the Võro (Võro Quickstart), the Kashubian (Kashubian Quickstart), the Silesian (Silesian Quickstart), the Rusyn (Rusyn Quickstart), the Lower Sorbian (Lower Sorbian Quickstart), the Aragonese (Aragonese Quickstart), the Kirundi (Kirundi Quickstart). Looking for localized guides? See the 🇵🇭 Umuna a Gabay iti omi-cli (Ilocano Quickstart). Looking for localized guides? See the 🇵🇭 Mga Unang Lakang gamit ang omi-cli (Cebuano Quickstart). Looking for localized guides? See the Diné bizaad (Navajo Quickstart). Looking for localized guides? See the føroysk byrjanarvegleiðing (Faroese Quickstart), the lëtzebuergesch Ufanksguide (Luxembourgish Quickstart), the Fryske flugge startgids (Frisian Quickstart), the stiùireadh tòiseachaidh Gàidhlig (Scottish Gaelic Quickstart), or the huanadenn deraouiñ e brezhoneg (Breton Quickstart). Looking for localized guides? See the guida rapida n sicilianu (Sicilian Quickstart), the guida de començament rapid en occitan (Occitan Quickstart), the aratohu tere mō te reo Māori (Māori Quickstart), the guía ñepyrũ pya'e avañe'ẽme (Guarani Quickstart), or the ئۇيغۇرچە تېز باشلاش قوللانمىسى (Uyghur Quickstart). Looking for localized guides? See the omi-cli ho Twi kasa mu (Twi Quickstart), the pituduh kapertama basa Bali (Balinese Quickstart), the mehato ea pele ka Sesotho (Southern Sotho Quickstart), the is primos passos in sardu (Sardinian Quickstart), or the ערשטע טריט מיט omi-cli (Yiddish Quickstart).

Auth

Two auth methods, both fully wired:

Method	Best for	How to use
Dev API key (omi_dev_*)	Agents, CI, headless, scoped permissions	omi auth login --api-key ... or env var
Firebase OAuth (Google/Apple)	Humans on a laptop	omi auth login --browser

The browser flow opens your default browser for OAuth, captures the code on a localhost callback, and stores a Firebase ID token + refresh token. The ID token is auto-refreshed before each request when it's near expiry — you shouldn't need to think about it.

omi auth login                  # interactive picker (browser or key)
omi auth login --browser        # force OAuth (default provider: google)
omi auth login --browser --provider apple
omi auth login --api-key K      # force API-key path
omi auth login < key.txt        # piped key, useful in CI
omi auth status                 # show profile + masked credential + expiry
omi auth whoami                 # round-trip to verify the credential works
omi auth refresh                # force a Firebase refresh (no-op for API keys)
omi auth logout                 # wipe the credential

An API-key login candidate is checked before replacing the saved credentials. If verification rejects it with HTTP 401 or 403, the existing profile and active profile selection remain unchanged. Other HTTP errors retain the existing store-and-warn behavior. A transport failure leaves saved credentials unchanged; browser OAuth is a separate flow.

You can also set a non-empty OMI_API_KEY in the environment to override the saved authentication for cloud API requests - handy in containers and CI. The key is validated even when the selected profile already has credentials; an invalid override fails before any cloud API request. Local Desktop commands use their separate local token, and auth status reports the saved profile. Saved credentials are not changed, and profile settings such as the API base URL still apply:

export OMI_API_KEY=omi_dev_...
omi memory list

Profiles

State lives at ~/.omi/config.toml (overridable via $OMI_CONFIG). The file holds one or more named profiles, each with its own auth method and API base. Saving configuration preserves unknown settings at both the root and profile levels, so editing a known setting does not discard extensions from newer clients. Switch between them with --profile:

omi config profile use work
omi auth login                  # logs in the active profile (work)
omi --profile personal memory list

Common config:

omi config show
omi config path
omi config set api_base https://api.staging.omi.me
omi config set local_api_url http://127.0.0.1:47778
omi config set local_token ...
omi config profile list
omi config profile delete old-account --yes

Local Omi Desktop API

omi local talks to a running Omi Desktop local API. Configure the active profile once, or use env vars for ephemeral agent sessions:

omi local configure --url http://127.0.0.1:47778 --token ...
export OMI_LOCAL_API_URL=http://127.0.0.1:47778
export OMI_LOCAL_TOKEN=...

Common local tools:

omi --json local status
omi --json local tools
omi --json local call search_screen_history --args-json '{"query":"pricing page","days":7}'
omi --json local search-screen "pricing page" --days 7 --app Safari
omi --json local screenshot 123 --output /tmp/omi-shot.jpg
omi --json local recap --days-ago 1
omi --json local sql "SELECT appName, COUNT(*) FROM screenshots GROUP BY appName"
omi --json local task search "taxes" --include-completed

Agent screen-history workflow:

1. Check availability with omi --json local status; look for screen_history_available, screenshot_count, and indexed_screenshot_count.
2. Discover tool schemas with omi --json local tools.
3. Search OCR/screen history with omi --json local search-screen "query" --days 7 or run exact SQL against screenshots when you need app/window filters.
4. Use a returned screenshot_id with omi --json local screenshot <id> --output /tmp/omi-shot.jpg.
5. Validate the file before handing it to vision tooling, for example file /tmp/omi-shot.jpg.

When semantic search returns no results, JSON mode also tries a literal substring search across app names, window titles, and OCR text. In this fallback, % and _ in the query or --app filter match those characters literally, rather than acting as SQL wildcards.

If pixels are not available, JSON-mode errors preserve Desktop's structured fields such as status_code, error, reason, hint, and screenshot_id. For example, screenshot_pending means the frame is still in the active video segment; retry shortly or choose an older screenshot ID from search results.

Task writes should only run after the user clearly asks for that change:

omi --json local task complete task_123
omi --json local task delete task_123 --yes

Apply the requested time window to exact screen search

The exact app/window/OCR fallback for omi --json local search-screen honors the same rolling --days window as semantic search.

Command surface

The full tree (run omi --help for the live version):

omi
├── auth
│   ├── login [--browser] [--api-key KEY]
│   ├── logout
│   ├── status
│   ├── whoami
│   └── refresh
├── config
│   ├── show
│   ├── path
│   ├── set <key> <value>
│   └── profile
│       ├── list
│       ├── use <name>
│       └── delete <name>
├── memory
│   ├── list [--limit N] [--offset N] [--categories ...]
│   ├── get <id>
│   ├── create <content> [--category ...] [--visibility ...] [--tag ...]
│   ├── update <id> [--content ...] [--category ...] [--visibility ...] [--tag ...]
│   └── delete <id> [-y]
├── conversation
│   ├── list [--limit N] [--start-date ...] [--end-date ...] [--include-transcript]
│   ├── get <id> [--include-transcript]
│   ├── create [--text ...] [--text-source ...] [...]
│   ├── from-segments <file.json> [--source ...]
│   ├── update <id> [--title ...] [--discarded/--no-discarded]
│   └── delete <id> [-y]
├── action-item
│   ├── list [--completed/--open] [--conversation-id ...] [...]
│   ├── get <id>
│   ├── create <description> [--due-at ...]
│   ├── update <id> [--description ...] [--completed/--open] [--due-at ...]
│   ├── complete <id>
│   └── delete <id> [-y]
├── local
│   ├── configure --url URL --token TOKEN
│   ├── status
│   ├── tools
│   ├── call <tool> [--args-json JSON]
│   ├── search-screen <query> [--days N] [--app NAME]
│   ├── screenshot <id> [--output PATH]
│   ├── recap [--days-ago N]
│   ├── sql <query>
│   └── task
│       ├── search <query> [--include-completed]
│       ├── complete <id>
│       └── delete <id> [-y]
└── goal
    ├── list [--limit N] [--include-inactive]
    ├── get <id>
    ├── create <title> --target N [--type ...] [--current N] [--unit ...]
    ├── update <id> [--unit ... | --clear-unit] [...]
    ├── progress <id> <value>
    ├── history <id> [--days N]
    └── delete <id> [-y]

conversation from-segments reads JSON files as UTF-8 (with or without a BOM), UTF-16, or UTF-32, independently of the system's default text encoding. Both transcript JSON and local call --args-json require finite numbers: NaN, Infinity, -Infinity, and values outside Python's finite floating-point range are rejected before opening an API client. In --json mode, these input errors are reported as JSON on stderr.

Goal numeric options and progress values must also be finite. NaN, infinities, and overflowing exponents are rejected before an API request.

action-item get searches successive API pages until it finds the ID or reaches the end of the results. It can retrieve items beyond the first 1,000; looking up an older or missing item may require several API requests.

Global flags

--json                 Emit JSON to stdout (machine-readable, agent-friendly).
--profile, -p NAME     Use a specific profile.
--api-base URL         Override the API base URL.
--verbose, -v          Log HTTP traffic to stderr.
--no-color             Disable colored output (also honors $NO_COLOR).
--version              Print the version.
--help                 Show contextual help.

Exit codes (stable contract)

0  success
1  usage error (bad flags, missing args, validation)
2  auth error (no creds, expired token, insufficient scope)
3  server error (5xx, connection failure)
4  rate limited (429) — retry recommended
5  not found (404)

For agents

The CLI is built so an LLM can use it without a wrapper:

• --json returns valid JSON to stdout. Nothing else writes to stdout in JSON mode (errors go to stderr as {"error": "...", "detail": "..."}).
• Use omi --json version for a machine-readable version object ({"version": "..."}). omi version and the eager omi --version flag retain their plain-text output.
• Stable exit codes (above) let an agent disambiguate retryable vs terminal errors.
• Successful resource delete --yes commands preserve the API response in JSON mode. A successful response without a body is emitted as JSON null.
• Rate-limit errors include a Retry-After window in the message and surface the policy name (dev:conversations, etc.) so an agent can back off intelligently.
• OMI_API_KEY and OMI_API_BASE env vars work without any prior auth login.
• OMI_LOCAL_API_URL and OMI_LOCAL_TOKEN override profile-local Desktop API settings for omi local.

See examples/agent_quickstart.md for a worked example.

Rate limits

The dev API enforces per-policy hourly limits:

Policy	Limit
dev:conversations	25/hour
dev:memories	120/hour
dev:memories_batch	15/hour

The CLI retries 429 automatically with exponential backoff and honors the server's Retry-After hint where present. After all retries are exhausted you get exit code 4 plus a message telling you how long to wait.

POST and PATCH requests are not automatically replayed after an ambiguous transport failure or a server error: the server may already have applied the write. These failures return exit code 3 with an outcome unknown message. Check the resource before trying again. Connection-establishment failures and rate-limit responses still retry; read retries are unchanged.

Allow clearing an action item due date

omi action-item update ID --clear-due-at removes a due date on servers supporting explicit null PATCH fields (backend fix #13029). It cannot be combined with --due-at. Omitting both leaves the date unchanged.

Preserve ambiguous sql table output

omi --json local sql keeps ambiguous or truncated display tables under text rather than silently dropping cells. Structured Desktop responses pass through unchanged; the text display is not a lossless SQL wire format.

Datetime options

Conversation and action-item datetime options accept ISO timestamps with Z (UTC), numeric offsets, and optional fractional seconds, for example --due-at 2026-09-08T12:30:00Z or --start-date 2026-09-08T12:30:00.123456+05:30. Offsets are preserved in API requests. Date-only values and timestamps without an offset remain supported; the CLI does not assign a timezone to those inputs.

Development

# Editable install with dev extras
pip install -e .[dev]

# Run the test suite
pytest -q

# Lint
black --check --line-length 120 --skip-string-normalization sdks/python-cli/
mypy omi_cli

# Build a wheel + sdist (no upload, no tag)
bash release.sh --build-only

License

MIT — see LICENSE.

• Кыргызча (Kyrgyz)
• Furlan (Friulian)
• Qırımtatarca (Crimean Tatar)