openmetadata-cli

openmetadata-cli provides the omd binary, a Rust CLI for OpenMetadata.

It is designed to work well in three modes:

• direct shell use by operators and engineers
• structured CLI use by automation and AI agents
• MCP-backed use through omd mcp in compatible AI clients

What omd includes

• Curated high-value commands and + shortcuts
• Dynamic commands generated from the OpenMetadata OpenAPI spec
• JSON-friendly output for automation
• CSV export/import workflows for bulk metadata edits
• An MCP server mode for agent clients

Install

cargo install --git https://github.com/Romamo/openmetadata-cli

Or build from source:

cargo build --release
./target/release/omd --help

Build

cargo build
./target/debug/omd --help

Contributor tip: if you use direnv, this repo includes .envrc so each new shell in the project automatically exposes the local debug build as omd after:

brew install direnv
echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc
exec zsh
direnv allow
cargo build
omd --help

If you do not use direnv, the shortest local entrypoints are:

./target/debug/omd --help
# or, after creating the repo-local symlink:
./omd --help

Authentication

omd supports several auth flows, including direct token auth.

Typical non-interactive setup:

export OMD_HOST="https://your-openmetadata.example.com"
omd auth login --token-env-var OMD_TOKEN --headless
omd auth status

Agent-first defaults:

• Start with omd --schema before guessing dynamic command flags or request bodies.
• Use --format json or --output json in automation; both map to the same JSON envelope.
• For complex built-in mutations, prefer --json or --json-file over many bespoke flags.
• Use --headless with --token-env-var for non-interactive auth workflows.

Common CLI examples

Discover tables:

omd search "orders" --index table --limit 5 --output json

Read a specific entity:

omd get table sample_postgres.default.public.orders \
  --fields owners,tags,description \
  --output json

Trace lineage:

omd lineage table sample_postgres.default.public.orders \
  --up-depth 2 \
  --down-depth 0 \
  --output json

Bulk edit via CSV:

omd csv export \
  --entity-type table \
  --fields name,fullyQualifiedName,description \
  --limit 100 \
  --file /tmp/tables.csv

Use as an MCP server

omd mcp starts an MCP stdio server that exposes the curated metadata tool surface to compatible AI clients.

Generic MCP server config:

{
  "mcpServers": {
    "openmetadata": {
      "command": "/path/to/omd",
      "args": ["mcp"]
    }
  }
}

Ready-to-copy client examples live in examples/mcp.

You can smoke test the MCP server locally with:

automation/scripts/smoke-test-mcp.sh /path/to/omd

Workflow docs

For user-and-agent friendly operating guidance, start with:

• CONTEXT.md
• docs/playbooks/discover-entities.md
• docs/playbooks/read-entity-details.md
• docs/playbooks/trace-lineage.md
• docs/playbooks/apply-metadata-changes.md
• docs/playbooks/bulk-edit-csv.md
• docs/playbooks/connect-mcp-client.md

Automation assets

The repo includes a small set of reusable automation artifacts:

• examples/mcp for client config examples
• automation/scripts for shell helpers
• .agents/skills for the bundled agent skill set

Useful local checks:

automation/scripts/agent-skills-preflight.sh
automation/scripts/lint-agent-skills.sh
automation/scripts/check-agent-skills-inventory.sh
automation/scripts/new-agent-skills-smoke-test.sh
automation/scripts/next-agent-skills-smoke-test.sh
automation/scripts/summarize-agent-skills-smoke-tests.sh

Repository docs

• AGENTS.md for coding agents modifying this repo
• docs/use-cases.md for practical workflow examples
• docs/skills-packaging.md for canonical source and sync rules
• docs/agent-skills-smoke-tests.md for prompt-based validation in real agent clients
• docs/validation/README.md for validation report generation and review
• docs/validated-workflows.md for the current sandbox-validated workflow summary

Sandbox validation results are stored in docs/validation/.