GitHub - jaumecornado/odooapi-cli

A Go CLI to connect to Odoo via JSON-RPC (/jsonrpc) with stable machine-readable output for AI agents.

Features

Credential resolution by priority: flag > env > config
Persistent local config in ~/.config/odooapi-cli/config.yaml
Stable --json envelope for automations
Odoo RPC helpers for common tasks:
- connectivity check (ping)
- identity check (whoami)
- list models (models list)
- inspect fields (fields describe)
- search/read/call records (records ...)
Action catalog for agents:
- list/inspect available actions (actions list, actions describe)
- run curated actions with validated inputs (actions run)

Installation

Homebrew (recommended for macOS)

brew tap jaumecornado/tap
brew install odooapi
odooapi help

Direct binary install (macOS)

# Apple Silicon
curl -L -o odooapi.tar.gz \
  https://github.com/jaumecornado/odooapi-cli/releases/latest/download/odooapi-cli_<version>_darwin_arm64.tar.gz

# Intel
curl -L -o odooapi.tar.gz \
  https://github.com/jaumecornado/odooapi-cli/releases/latest/download/odooapi-cli_<version>_darwin_amd64.tar.gz

tar -xzf odooapi.tar.gz
chmod +x odooapi
mv odooapi /usr/local/bin/odooapi
odooapi help

Go install (development)

go install github.com/jaumecornado/odooapi-cli/cmd/odooapi@latest
odooapi help

Commands

odooapi auth set --base-url <url> --db <database> --username <user> --password <password>
odooapi auth status
odooapi ping
odooapi whoami
odooapi models list
odooapi fields describe <model>
odooapi records search <model>
odooapi records read <model> <id|id,id...>
odooapi records call <model> <method>
odooapi actions list
odooapi actions describe <action-id>
odooapi actions run <action-id>

Global option:

--json stable output format for agents/automations.

Environment variables

ODOO_URL or ODOO_BASE_URL
ODOO_DB or ODOO_DATABASE
ODOO_USERNAME or ODOO_LOGIN
ODOO_PASSWORD or ODOO_API_KEY
ODOOCLI_CONFIG_PATH (optional override for config file path)

Examples

# configure once
odooapi auth set \
  --base-url "https://mycompany.odoo.com" \
  --db "mycompany" \
  --username "bot@mycompany.com" \
  --password "$ODOO_PASSWORD"

# verify config
odooapi auth status

# check RPC connectivity
odooapi ping --json

# check authenticated identity
odooapi whoami --json

# list models
odooapi models list --filter partner --limit 50

# inspect fields
odooapi fields describe res.partner --attributes string,type,required,readonly,relation

# search records
odooapi records search res.partner \
  --domain '[["is_company","=",true]]' \
  --fields name,email,phone \
  --limit 20 \
  --json

# read records by ID
odooapi records read res.partner 7,12,33 --fields name,email --json

# generic model method call (execute_kw)
odooapi records call res.partner search_count \
  --args '[[["is_company","=",true]]]' \
  --kwargs '{}' \
  --json

# discover agent-friendly actions
odooapi actions list --json
odooapi actions describe odoo.record.search_read --json

# run an action (no auth required)
odooapi actions run odoo.system.version --json

# run an authenticated action
odooapi actions run odoo.record.search_read \
  --model res.partner \
  --domain '[["is_company","=",true]]' \
  --fields name,email \
  --limit 25 \
  --json

JSON output contract

Success response:

{
  "version": "v1",
  "success": true,
  "command": "records search",
  "message": "operation executed",
  "data": {"model": "res.partner", "method": "search_read", "result": []}
}

Error response:

{
  "version": "v1",
  "success": false,
  "command": "records search",
  "error": {
    "code": "MISSING_CREDENTIALS",
    "message": "missing Odoo credentials: database, username, password"
  }
}

macOS distribution

The project includes a GoReleaser release pipeline that generates:

darwin/amd64 and darwin/arm64 binaries
checksums.txt
Homebrew tap publication

Expected GitHub Actions release secrets:

HOMEBREW_TAP_OWNER=jaumecornado
HOMEBREW_TAP_NAME=homebrew-tap
HOMEBREW_TAP_GITHUB_TOKEN

Notes

This CLI currently targets Odoo JSON-RPC (/jsonrpc) as documented in Odoo external API references for Odoo 18.0.