sap-odata-cli

name	sap-odata-cli
description	Query and inspect SAP OData services with the sap-odata CLI — service discovery, entity metadata and SAP/UI5 annotations, test queries, Fiori-readiness lint, service health checks, and offline EDMX browsing. Use when the user asks about SAP OData or Gateway services, entity sets, $metadata, SAP annotations, Fiori readiness, or wants live data samples from an SAP system.

sap-odata CLI for agents

sap-odata is a read-only SAP OData explorer. It never creates, updates, or deletes business data on the SAP side — every SAP-facing operation is a GET. The only things it mutates are its own local files (profiles in connections.toml, the offline EDMX library).

Ground rules

• Add --json to any command whose output you parse. Default output is a human table. JSON goes to stdout; progress banners and --verbose HTTP traces go to stderr — parse stdout only.
• Never run sap-odata setup — it is an interactive wizard and will hang a non-interactive shell. Profiles are set up by the user (wizard or desktop app). If no profile exists, ask the user to create one; for scripted/CI use, profile add with flags or SAP_BASE_URL/SAP_CLIENT/SAP_USER/SAP_PASSWORD env vars work non-interactively.
• Never put passwords in command lines you compose. Credentials live in the OS keyring (or env vars the user set). If auth is missing, say so — don't invent --password values.
• Prefer small probes. Use --top 5 (or less) for samples; use --count --top 0 when only a row count is needed.
• Exit codes are meaningful: non-zero = failure. verify exits 1 if any entity-set probe failed; lint --fail-on <warn|miss> exits non-zero at that severity — both are CI-gate friendly.

Orientation — what system, what services

sap-odata profile list                      # configured systems + auth state
sap-odata -p DEV services -f <text> --json  # find services (substring match)
sap-odata -p DEV -s <SERVICE> entities      # entity sets in a service

-s accepts a technical name (API_BUSINESS_PARTNER, resolved via the Gateway catalog), a full path (/sap/opu/odata/sap/... — required when the catalog is unpublished, common for V4), or a per-profile alias.

Inspect an entity

sap-odata -p DEV -s API_BUSINESS_PARTNER describe A_BusinessPartner --json

describe --json is the highest-density command: properties, keys, nav props, labels, plus parsed SAP/UI5 annotations (UI.LineItem columns, UI.SelectionFields, value helps, field control, text arrangement, search/ count/expand capabilities). Use it before composing queries — it tells you which properties are filterable/sortable and what the Fiori defaults are.

For raw or bulk annotation questions:

sap-odata -p DEV -s <SVC> annotations --namespace UI --json   # by vocabulary
sap-odata -p DEV -s <SVC> annotations --filter <text> --json  # by substring
sap-odata -p DEV -s <SVC> metadata > svc.edmx                 # raw $metadata (stdout is clean XML)

Query data

# Preview the URL without sending anything (always safe):
sap-odata -p DEV -s <SVC> build <EntitySet> --filter "..." --top 5

# Execute:
sap-odata -p DEV -s <SVC> run <EntitySet> \
  --select Col1,Col2 --filter "Col1 eq 'X'" --orderby "Col2 desc" \
  --top 5 --json

Useful flags: --key "'0001'" (single entity; composite: --key "SalesOrder='1',Item='10'"), --expand to_Item, --in Prop V1 V2 V3 (expands to OR'd equality, quoting handled), --count (adds $inlinecount/$count).

JSON shape passes the server response through: V2 rows are under .d.results[], V4 rows under .value[]. Check entities output or the service list's version column to know which.

Health checks and lint

sap-odata -p DEV -s <SVC> verify --json     # probe every entity set; exit 1 on any FAIL
sap-odata -p DEV -s <SVC> lint --fail-on miss --json   # Fiori-readiness gate

lint --json findings carry severity, stable code, suggested_cds (e.g. @UI.headerInfo) and why_in_fiori — quote those directly when advising on CDS annotation fixes.

Offline EDMX library (no network needed)

The library caches $metadata documents locally. The CLI manages it; browsing cached services with describe/lint is desktop-app-only today.

sap-odata offline list                              # buckets
sap-odata offline list --profile "DEV (offline)"    # services + ids in a bucket
sap-odata offline import file.edmx --label MYSVC    # ingest a hand-carried EDMX
sap-odata -p DEV -s <SVC> offline save              # capture from a live system

To answer metadata questions offline, read the cached file directly — it is plain EDMX XML at {config}/offline/<bucket-slug>/<service_id>.edmx, where {config} is the directory sap-odata profile where prints. Parse entity types, properties, and annotations straight from the XML.

offline import accepts API-Hub .edmx, /IWFND/GW_CLIENT "Save Response" XML, curl <base>/$metadata dumps. offline delete prompts for confirmation — a script must pass -y; treat it as destructive and only run it when the user asked.

When things fail

Error text includes SAP-specific hints — surface them to the user verbatim, they name the fixing transaction. Common cases:

Signal	Meaning	Your move
not registered in /IWFND/MAINT_SERVICE	service not activated in Gateway	tell the user; it needs an admin
403 on catalog	user lacks catalog authorization	tell the user (roles / SU53)
browser sign-in incomplete / HTML instead of OData	Browser SSO session expired	user must run sap-odata signout <profile> and re-sign-in from the desktop app — you cannot do this
keyring locked / keyring corrupt in profile list	OS credential store issue	user unlocks/repairs the credential store; do NOT re-add the profile
V4 service not found via catalog search	V4 catalog node often unpublished	use the full /sap/opu/odata4/... path with -s

For anything unclear, re-run the failing command with --verbose and read the HTTP trace on stderr (auth headers are redacted; safe to inspect).