This repository is now replaced by https://github.com/exploreomni/cli
Automation-first Omni CLI for agents, workflows, and machine-to-machine use.
This repository is not trying to be a human-first terminal app. The primary goal is a stable command contract that other tools can call safely:
- JSON-first output for automation
- stable exit codes
- machine-readable command discovery via
omni schema - explicit auth/profile handling
- raw API access via
omni api call
The CLI is built from a generated Omni OpenAPI client plus handwritten command and auth logic. Agent usage mapping is documented in docs/agent-command-map.md.
- wraps the Omni API in typed command groups such as
documents,models,connections,folders,labels,schedules,dashboards,query,users, andscim - supports PAT auth, org API keys, or both on one profile
- uses browser login for PAT setup
- supports keychain-backed secrets on macOS with config-file fallback
- provides
doctor,schema,exit-codes, and rawapi callfor agent/runtime integration - includes an interactive connection creation wizard for supported dialects, with
--filestill available for automation
- Success payloads are written to
stdout. - Error payloads are written to
stderr. --jsonis the preferred mode for callers and agents.--plainprovides stable TSV-style output for list-shaped responses.omni exit-codesprints the stable exit-code and error-code contract.omni schema [command path]prints machine-readable command metadata.OMNI_ENABLE_COMMANDScan restrict the allowed top-level command set for embedded/agent use.
Error shape in --json mode:
{
"error": {
"code": "AUTH_UNAUTHORIZED",
"message": "token unauthorized for Omni API",
"details": {}
}
}Profiles live in ~/.omni/config.json by default.
pat: PAT acquired through browser loginorg: org API key entered directlyboth: PAT plus org key on one profile
Runtime behavior:
- general commands use the profile's
default_auth admin,users, andscimrequire org auth automatically--auth pat|orgoverrides the auth used for the current command--tokenand--token-typestill work as legacy/manual overrides
PAT flow details are documented in docs/pat-auth-flow.md.
Interactive setup:
omni setup
omni setup --profile prod --url https://acme.omniapp.co --auth-mode both --org-key "$OMNI_ORG_KEY" --default-auth patNon-interactive setup:
omni setup --non-interactive --profile prod --url https://acme.omniapp.co --auth-mode org --org-key "$OMNI_ORG_KEY" --token-store auto
omni auth add --name prod --url https://acme.omniapp.co --auth-mode both --org-key "$OMNI_ORG_KEY" --default-auth pat --token-store keychain
omni auth use prod
omni auth show --profile prod --jsonSupported environment variables:
OMNI_PROFILEOMNI_URLOMNI_AUTHOMNI_ORG_KEYOMNI_PATfor manual override only; normal PAT setup is browser-basedOMNI_TOKENOMNI_TOKEN_TYPEOMNI_CONFIGOMNI_PLAINOMNI_NO_INPUTOMNI_ENABLE_COMMANDS
Global flags can be provided before or after the command path:
omni --json documents list
omni documents list --jsonCommand-local flags should be placed before positional arguments. For example:
omni documents rename --name "Q1 Dashboard" wk_abc123
omni folders create --scope organization "Team Reports"
omni labels create --homepage true financeomni schema
omni schema documents permissions
omni exit-codes --json
omni doctor --json
omni api call --method GET --path /api/v1/documents
omni query run --file query.json --result-type json --wait
omni user-attributes list --json
OMNI_ENABLE_COMMANDS=query,documents omni documents list --page-size 20 --jsonTop-level commands:
schemaexit-codesdoctorcompletionsetupauthdocumentsmodelsconnectionsfolderslabelsschedulesdashboardsagenticembedunstableuser-attributesadminusersscimaiapiqueryjobsversion
High-value subcommands:
omni auth add|list|remove|use|show|whoamiomni documents list|get|create|delete|rename|move|draft create|draft discard|duplicate|favorite add|favorite remove|access list|permissions get|permissions add|permissions update|permissions revoke|permissions settings|label add|label remove|labels bulk-update|queries|transfer-ownershipomni models list|get|create|refresh|validate|branch delete|branch merge|cache-reset|topics list|get|update|delete|views list|update|delete|fields create|update|delete|git get|create|update|delete|sync|migrate|content-validator get|replace|yaml get|create|deleteomni connections list|create|update|dbt get|dbt update|dbt delete|schedules list|schedules create|schedules get|schedules update|schedules delete|environments list|environments create|environments update|environments deleteomni folders list|create|delete|permissions get|permissions add|permissions update|permissions revokeomni labels list|get|create|update|deleteomni schedules list|create|get|update|delete|pause|resume|trigger|recipients get|recipients add|recipients remove|transfer-ownershipomni dashboards download|download-status|download-file|filters get|filters updateomni agentic submit|status|cancel|resultomni embed sso generate-sessionomni unstable documents export|importomni user-attributes listomni admin users listomni admin groups listomni users list-email-only|create-email-only|create-email-only-bulk|roles get|roles assign|group-roles get|group-roles assignomni scim users list|get|create|update|replace|delete|groups list|get|create|update|replace|delete|embed-users list|get|deleteomni ai generate-query|workbook|pick-topicomni api callomni query runomni jobs status
The bundled OpenAPI coverage report is tracked in:
omni connections create can run interactively in a terminal, or accept --file JSON for automation.
Supported interactive dialects:
postgresredshiftmysqlmariadbmssqlsnowflakedatabricksbigqueryathenamotherduckclickhouseexasolstarrockstrino
Examples:
omni connections create
omni connections create --file connection.json
omni connections update 550e8400-e29b-41d4-a716-446655440000 --file connection-update.json
omni connections environments list
omni connections schedules list 550e8400-e29b-41d4-a716-446655440000These are still useful when developing the CLI, but they are secondary to the machine-facing contract.
omni completion zsh > ~/.zsh/completions/_omni
omni documents list --page-size 20
omni documents get wk_abc123
omni documents rename --name "Executive Dashboard" wk_abc123
omni documents permissions add wk_abc123 --file permits.json
omni models list --name marketing
omni folders permissions get 550e8400-e29b-41d4-a716-446655440000
omni labels create --homepage true finance
omni schedules create --file schedule.json
omni schedules recipients add 550e8400-e29b-41d4-a716-446655440000 --file recipients.json
omni dashboards filters update wk_abc123 --file dashboard-filters.json
omni agentic submit --file agentic-job.json
omni embed sso generate-session --file embed-session.json
omni unstable documents export wk_abc123
omni users list-email-only --page-size 20
omni scim users list --count 20
omni ai generate-query --model-id 550e8400-e29b-41d4-a716-446655440000 --prompt "Revenue by month"
omni jobs status 12345cmd/omni: entrypointinternal/cli: handwritten command handlers and runtime wiringinternal/auth: auth resolution and profile behaviorinternal/config: config load/save and profile formatinternal/client: handwritten client wrappersinternal/client/gen: generated OpenAPI client codeinternal/output: stdout/stderr and plain/json formatting helpersinternal/secret: keychain/config credential storage abstractionapi/openapi.json: checked-in Omni API specscripts/update_openapi.sh: fetch and normalize an Omni OpenAPI specscripts/generate_client.sh: regenerate the typed client
make build
make test
make coverage-reportRefresh the API client:
./scripts/update_openapi.sh https://your-instance.omniapp.co/openapi.json
go generate ./internal/client/genBuild release artifacts locally:
goreleaser release --snapshot --clean