CLI Commands Reference¶

The oaa CLI is built on python-fire. Every command below is invoked as oaa <command> [args] [--flags]. Positional arguments can be passed by position or by name (--name=value); this reference uses --name=value form throughout for clarity.

Most commands support a --json flag (noted per-command below). When --json is passed, the command prints its return value as indented JSON to stdout instead of its normal human-readable text. This is useful for piping output into jq or other tooling.

Commands are grouped below by purpose:

Core Commands
Introspection Commands
Data Inspection Commands
Scaffolding Commands
Analysis & Review Commands
Data Safety Commands
Veza API Commands
Query & Diff Commands

Core Commands¶

`validate_config`¶

Validate a config.yaml file without running a full sync. Checks config structure, connection modules, and preflight conditions.

Usage:

oaa validate_config --config_file=./config.yaml
oaa validate_config --config_file=./config.yaml --test_connectivity=True

Argument	Type	Required	Description
`config_file`	`string`	Yes	Path to the `config.yaml` file.
`test_connectivity`	`bool`	No	Also test live connections to data sources. Default: `False`.

--json supported (returns {"valid": bool, "messages": [...]}; text mode prints each message on its own line).

`explode_config`¶

Resolve all !include tags in a config.yaml and write the fully expanded result to a plain YAML file. Useful for sanity-checking large, compartmentalized configs.

Usage:

oaa explode_config --config_file=./config.yaml
oaa explode_config --config_file=./config.yaml --output=./out.yaml

Argument	Type	Required	Description
`config_file`	`string`	Yes	Path to the config file (may use `!include`, `!include_dir_list`, `!include_dir_named`, `!include_dir_merge_list`, `!include_dir_merge_named`).
`output`	`string`	No	Path to write the exploded YAML. Defaults to `<config_file stem>.exploded.yaml` next to the input.

--json supported (returns {"output_path": "..."}).

Exits 1 if config_file does not exist.

`version`¶

Print the installed oaa-runner package version.

Usage:

oaa version

--json supported (returns {"version": "..."}).

`show_sample`¶

List bundled OAA integration samples or copy a sample to a destination directory. Supports filtering by pattern and downloading external sample bundles from a ZIP URL.

Usage:

oaa show_sample --list
oaa show_sample --name=custom-app-users-groups-roles
oaa show_sample --name=custom-app-users-groups-roles --output=./my-app
oaa show_sample --filter=hris
oaa show_sample --url=https://example.com/samples.zip

Argument	Type	Required	Description
`name`	`string`	No	Sample name to copy (e.g. `custom-app-users-groups-roles`). If omitted with no other flags, lists samples.
`list`	`bool`	No	Explicitly show list of samples. Default: `True` if `name` is not provided.
`filter`	`string`	No	Filter samples by substring match (case-insensitive).
`output`	`string`	No	Destination path for copying a sample. Defaults to `./<name>` in current directory.
`url`	`string`	No	Download and cache an external sample bundle from this URL (must be a ZIP file).

--json supported (returns {"samples": [...]} in list mode or {"name", "output_path", "files": [...]} in copy mode).

Introspection Commands¶

`list_transforms`¶

List all registered field transform functions with their mode and description.

Usage:

oaa list_transforms
oaa list_transforms --json

No arguments. --json supported.

`list_entity_types`¶

List all Veza entity/destination types (LocalUser, LocalRole, EnrichedEntity, etc.) with their required mapping fields.

Usage:

oaa list_entity_types

No arguments. --json supported.

`show_entity`¶

Show the full schema for one entity type: required mapping fields, the corresponding oaaclient model fields (required/optional), and available relationship methods (add_*).

Usage:

oaa show_entity --entity_type=LocalRole

Argument	Type	Required	Description
`entity_type`	`string`	Yes	One of the entity types returned by `list_entity_types`.

--json supported. Exits 1 with a list of available types on stderr if entity_type is unknown.

`list_hooks`¶

List all OAAHookEvent values and every registered common hook (name, phase, event, description).

Usage:

oaa list_hooks

No arguments. --json supported.

`config_schema`¶

Print the full JSON Schema for config.yaml (generated from the ConfigV2 Pydantic model).

Usage:

oaa config_schema

No arguments. This command has no dedicated text renderer, so output is JSON-formatted whether or not --json is passed.

Data Inspection Commands¶

`test_transform`¶

Run a single named transform against a sample value, without touching a config file. Useful for checking a transform’s behavior before wiring it into field_mapping.

Usage:

oaa test_transform --name=date_convert --value="2024-01-15"

Argument	Type	Required	Description
`name`	`string`	Yes	Transform name (e.g. `make_hash`, `date_convert`). See `list_transforms`.
`value`	any	Yes	The value to transform.
`options`	`dict`	No	Options dict for factory-style transforms.

--json supported (returns {"name", "input", "output"}). Exits 1 with available transform names on stderr if name is unknown.

`check_env`¶

Scan a config file for ${VAR} references and verify each referenced environment variable is actually set.

Usage:

oaa check_env --config_file=./config.yaml

Argument	Type	Required	Description
`config_file`	`string`	No	Path to config file. Default: `config.yaml` in cwd.

--json supported. In text mode, exits 1 if any referenced variable is missing (with a count on stderr); with --json, returns the data without exiting, so scripting callers must check success/missing_count themselves.

`preview`¶

Fetch raw data from a source (before field mappings/transforms are applied) and print the first N records.

Usage:

oaa preview --source_name=users --limit=5

Argument	Type	Required	Description
`source_name`	`string`	Yes	Name of the source in `config.yaml`.
`limit`	`int`	No	Number of records to show. Default: `10`.
`config_file`	`string`	No	Path to config file. Default: `config.yaml` in cwd.

--json supported. Exits 1 if the source is not found (available sources listed on stderr).

`preview_mapped`¶

Like preview, but applies field mappings and transforms first, showing the records as they would appear after transformation.

Usage:

oaa preview_mapped --source_name=users --limit=5

Arguments identical to preview. --json supported.

`validate_mappings`¶

Check every source’s field_mapping references against the actual field names present in that source’s fetched data. Flags missing fields and suggests close matches (via fuzzy matching) for likely typos.

Usage:

oaa validate_mappings --config_file=./config.yaml

Argument	Type	Required	Description
`config_file`	`string`	No	Path to config file. Default: `config.yaml` in cwd.

--json supported. In text mode, exits 1 if any field is missing; with --json, returns the data without exiting.

Scaffolding Commands¶

`init`¶

Scaffold a new OAA integration project from templates: config.yaml, Python modules, sample.env, requirements.txt, and README.md.

Usage:

oaa init myapp --num_sources=3
oaa init myapp --source_names=users,roles --folder_location=./integrations
oaa init myapp --no_mocks=True

Argument	Type	Required	Description
`name`	`string`	Yes	Integration name (used for directory and module names).
`num_sources`	`int`	No	Number of source entries in `config.yaml`. Default: `5`.
`folder_location`	`string`	No	Output directory. Defaults to the current working directory.
`source_names`	`string`	No	Comma-separated source names; overrides `num_sources`.
`no_mocks`	`bool`	No	Skip generating the mocks module file. Default: `False`.

--json supported. Returns/prints "Done!" on success.

`generate_source`¶

Add a new source (and connection, if needed) to an existing config.yaml. For rest-api and custom types, also creates a Python module file from the standard template.

Usage:

oaa generate_source rest-api myapi --config_file=./config.yaml
oaa generate_source csv users
oaa generate_source custom myservice

Argument	Type	Required	Description
`source_type`	`string`	Yes	One of `rest-api`, `csv`, `custom`.
`name`	`string`	Yes	Name for the source/connection (also used for the module file, for `rest-api`/`custom`).
`config_file`	`string`	No	Path to `config.yaml`. Default: `config.yaml` in cwd.

--json supported (returns details of what was created/updated). Exits 1 if source_type is unsupported, or if the target module file already exists.

`generate_hook`¶

Generate a hook function scaffold with the @hook decorator already applied for a given OAAHookEvent. Does not overwrite existing files.

Usage:

oaa generate_hook PRE_TRANSFORM --target=users
oaa generate_hook POST_PUSH_OAA

Argument	Type	Required	Description
`event`	`string`	Yes	`OAAHookEvent` name (e.g. `PRE_TRANSFORM`, `POST_PUSH_OAA`). See `list_hooks`.
`target`	`string`	No	Source name to target the hook to. If omitted, generates a generic hook file.

--json supported. Exits 1 with available event names on stderr if event is unknown. If the target file already exists, returns/prints a “skipped” result rather than overwriting it.

`assemble_fragments`¶

Splice per-entity fragment files into the shared config.yaml and *_mocks.py of an integration build. Fragments merge in entity order (users, groups, roles, resources). Permission map keys are collision-checked across fragments. Re-running is safe — existing mock fragment sections are replaced in place rather than duplicated.

Usage:

oaa assemble_fragments --root=./build

Argument	Type	Required	Description
`root`	`string`	Yes	Path to the integration build directory (must contain `config.yaml` and `fragments/` subdirectory).

--json supported (returns {"config_path", "mocks_path", "entities_merged": [...], "permission_map_keys_added": [...]}).

Exits 1 if config.yaml or fragments/ is missing, if a fragment has invalid YAML, or if permission_to_veza_map keys collide with non-identical values.

Analysis & Review Commands¶

Commands in this section perform static analysis and validation without pushing to Veza.

`validate_payload`¶

Validate an oaa run --save-json payload against its config.yaml. Reports field presence and null rates, date field formats, role permission coverage, relationship resolution, entity counts, leftover mock artifacts, and per-entity shape differences.

Usage:

oaa validate_payload --payload=./output.json --config=./config.yaml

Argument	Type	Required	Description
`payload`	`string`	Yes	Path to the `oaa run --save-json` output file.
`config`	`string`	Yes	Path to the integration’s `config.yaml`.

--json supported (returns structured report with field_checks, date_checks, role_checks, relationship_checks, shape_diffs, entity_counts, mock_removal).

Exits 1 when any check reports FAIL status.

`validate_integration`¶

Orchestrate a full integration validation pipeline: assemble fragments (if present) → check environment → validate config → validate mappings → review → mock run → validate payload → parse errors. Gracefully skips steps whose commands are not yet available.

Usage:

oaa validate_integration --path=./my-integration
oaa validate_integration --path=./my-integration --skip_mock=True
oaa validate_integration --path=./my-integration --live=True

Argument	Type	Required	Description
`path`	`string`	Yes	Path to the integration build directory.
`skip_mock`	`bool`	No	Run static checks only (steps 1-5); skip mock/live run. Default: `False`.
`live`	`bool`	No	Replace mock run with a real API run (requires live API credentials). Default: `False`.

--json supported (returns per-step status: {"steps": [{"step", "status", "detail", "data"}]}).

`review`¶

Static best-practices review for OAA integrations. Runs 26 deterministic checks across 9 categories: config, data structure, code quality, pagination, hooks, mocks, OAA objects, documentation, and config-vs-code consistency.

Usage:

oaa review --path=./my-integration
oaa review --path=./my-integration --rule=lazy_dict_table

Argument	Type	Required	Description
`path`	`string`	No	Integration directory to review. Default: `.` (current directory).
`rule`	`string`	No	Run a specific rule by ID (e.g. `lazy_dict_table`, `required_file_module`). If omitted, runs all 26 rules.

--json supported (returns {"integration_name", "path", "total", "passed", "warned", "failed", "success", "rules": [...]}).

Text mode prints pass/warn/fail per rule with file:line references and suggested fixes. Exits 1 if any rule fails.

`parse_errors`¶

Classify oaa run stderr/stdout into actionable error categories with embedded fix suggestions. Matches each line against known error patterns and returns structured results.

Usage:

oaa run --no-push 2>&1 | oaa parse_errors
oaa parse_errors --input=./run.log
oaa parse_errors --input=./run.log --category=auth_failure

Argument	Type	Required	Description
`input`	`string`	No	Path to a log file. If omitted, reads from stdin.
`category`	`string`	No	Filter to a single error category: `auth_failure`, `field_mapping`, `transform_error`, `shape_mismatch`, `relationship_error`, `pagination_error`, `hook_error`, `env_missing`, `unknown`.

--json supported (returns list of {"category", "message", "line_number", "suggestion"} dicts).

`parse_spec`¶

Parse an OpenAPI 3.x, Swagger 2.0, or Postman Collection v2.x spec and extract authentication schemes, endpoints, and schemas. Resolves all $ref chains for complete endpoint definitions.

Usage:

oaa parse_spec --input=./openapi.yaml
oaa parse_spec --input=https://api.example.com/openapi.json
oaa parse_spec --input=./spec.json --tag=users --include_schemas=True

Argument	Type	Required	Description
`input`	`string`	Yes	Path to spec file or HTTP(S) URL.
`tag`	`string`	No	Filter endpoints to a specific tag (OpenAPI/Swagger only).
`include_schemas`	`bool`	No	Include component/definition schemas in output. Default: `False`.

--json supported (returns {"spec_info", "auth_schemes": [...], "endpoints": [...], "summary": {...}, "schemas": {...}}).

Exits 1 if spec format is unrecognized or parsing fails.

Data Safety Commands¶

`anonymize`¶

Redact sensitive data in API response payloads before LLM ingestion. Replaces sensitive values (emails, UUIDs, IPs, tokens, SSNs) with deterministic fakes — same input always produces the same output. Three modes: default (anonymize), --audit (report what would be redacted), --schema (extract structure only, no values).

Usage:

oaa anonymize --input=./payload.json --output=./safe.json
oaa run --save-json=./payload.json 2>&1 | oaa anonymize
oaa anonymize --input=./payload.json --audit
oaa anonymize --input=./payload.json --schema

Argument	Type	Required	Description
`input`	`string`	No	Path to JSON file. If omitted, reads from stdin.
`output`	`string`	No	Path to write anonymized output. If omitted (with stdin input), prints to stdout.
`audit`	`bool`	No	Report what would be anonymized without modifying data. Default: `False`.
`schema`	`bool`	No	Extract field structure and types only; no values. Default: `False`.
`safe_fields`	`string`	No	Comma-separated list of field names to treat as safe (skip anonymization).

--json supported. Exits 1 if input file is not found or JSON is invalid.

Veza API Commands¶

Every command in this section requires a live Veza tenant connection. VEZA_URL and VEZA_API_KEY must be set (as environment variables or in config.yaml) — see Environment Variables.

`list_providers`¶

List all custom providers in the Veza tenant.

Usage:

oaa list_providers
oaa list_providers --details=True

Argument	Type	Required	Description
`details`	`bool`	No	Include schema details for each provider. Default: `False`.

--json supported.

`list_datasources`¶

List all datasources in the Veza tenant, optionally scoped to one provider.

Usage:

oaa list_datasources
oaa list_datasources --provider=my-app

Argument	Type	Required	Description
`provider`	`string`	No	Filter to datasources belonging to this provider name.

--json supported.

`show_provider`¶

Show full provider details, including the decoded application/resource type schema.

Usage:

oaa show_provider --name=my-app

Argument	Type	Required	Description
`name`	`string`	Yes	Provider name to look up.

--json supported. Exits 1 if the provider is not found.

`provider_status`¶

Show the current sync status for every datasource under a provider (last sync time, state, and any error).

Usage:

oaa provider_status --name=my-app

Argument	Type	Required	Description
`name`	`string`	Yes	Provider name to look up.

--json supported. Exits 1 if the provider is not found.

`delete_provider`¶

Delete a provider from the Veza tenant. This is a destructive operation.

Usage:

oaa delete_provider --name=my-app
oaa delete_provider --name=my-app --confirm=True

Argument	Type	Required	Description
`name`	`string`	Yes	Provider name to delete.
`confirm`	`bool`	No	Must be `True` to actually delete. Default: `False`.

Without --confirm=True, the command is a no-op that reports what would be deleted. --json supported.

`show_datasource`¶

Show datasource details and current sync status, optionally scoped to a specific provider.

Usage:

oaa show_datasource --name=my-datasource
oaa show_datasource --name=my-datasource --provider=my-app

Argument	Type	Required	Description
`name`	`string`	Yes	Datasource name to look up.
`provider`	`string`	No	Provider name to scope the search. If omitted, searches all providers.

--json supported. Exits 1 if the datasource (or, when given, the provider) is not found.

`delete_datasource`¶

Delete a datasource from the Veza tenant, optionally cascading to delete its linked provider too. This is a destructive operation.

Usage:

oaa delete_datasource --name=my-datasource --confirm=True
oaa delete_datasource --name=my-datasource --provider=my-app --confirm=True --cascade=True

Argument	Type	Required	Description
`name`	`string`	Yes	Datasource name to delete.
`provider`	`string`	No	Provider name to scope the search.
`confirm`	`bool`	No	Must be `True` to actually delete. Default: `False`.
`cascade`	`bool`	No	Also delete the linked provider. Default: `False`.

Without --confirm=True, the command is a no-op that reports what would be deleted. --json supported.

`rename_provider`¶

Rename a provider in the Veza tenant.

Usage:

oaa rename_provider --old_name=my-app --new_name=my-app-v2

Argument	Type	Required	Description
`old_name`	`string`	Yes	Current provider name.
`new_name`	`string`	Yes	New provider name.

--json supported. Fails gracefully (no exception, returns status flags) if old_name is not found or new_name already exists.

`export_provider`¶

Export a provider’s schema and datasource list to local files, as either a single JSON file or a directory of CSV files.

Usage:

oaa export_provider --name=my-app
oaa export_provider --name=my-app --format=json --output=./my-app.json
oaa export_provider --name=my-app --format=csv --output_dir=./my-app-export

Argument	Type	Required	Description
`name`	`string`	Yes	Provider name to export.
`format`	`string`	No	`json` or `csv`. Default: `json`.
`output`	`string`	No	Output file path (JSON format only). Defaults to `<name>_export.json`.
`output_dir`	`string`	No	Output directory (CSV format only). Defaults to `<name>_export`.

--json supported. Exits 1 for an unsupported format.

Query & Diff Commands¶

download_query, run_query, and compare_queries require VEZA_URL and VEZA_API_KEY to be set as environment variables (these commands read directly from os.environ, unlike the Veza API commands above, which also fall back to config.yaml values). diff_config requires no Veza API access at all.

`download_query`¶

Download a saved Veza query’s results.

Usage:

oaa download_query --query_id=abc123
oaa download_query --query_id=abc123 --output=./results.csv
oaa download_query --query_id=abc123 --output=./results.json --format=json

Argument	Type	Required	Description
`query_id`	`string`	Yes	The Veza saved query ID.
`output`	`string`	No	Output file path. If omitted, prints results to stdout.
`format`	`string`	No	`csv` or `json`. Default: `csv`.

--json supported. On failure, returns {"query_id", "error"} rather than raising.

`run_query`¶

Execute an ad-hoc Veza query (Veza Query Language) and return results.

Not yet available against the live Veza API. The endpoint this command calls (/api/v1/assessments/queries:execute) does not exist yet in the Veza API. The command is implemented and tested against mocked responses, ready for when the endpoint ships. Use download_query for saved query results today.

Usage:

oaa run_query --query="<VQL query>" --limit=50

Argument	Type	Required	Description
`query`	`string`	Yes	The Veza query string (Veza Query Language).
`limit`	`int`	No	Maximum number of results. Default: `100`.
`format`	`string`	No	`table`, `json`, or `csv`. Default: `table`.
`output`	`string`	No	Output file path. If omitted, prints to stdout.

--json supported. On failure, returns {"query", "error"} rather than raising.

`compare_queries`¶

Download two saved Veza queries and diff their results by a key field, reporting records that were added, removed, or changed.

Usage:

oaa compare_queries --query1=abc123 --query2=def456
oaa compare_queries --query1=abc123 --query2=def456 --key_field=user_id

Argument	Type	Required	Description
`query1`	`string`	Yes	First Veza saved query ID.
`query2`	`string`	Yes	Second Veza saved query ID.
`key_field`	`string`	No	Field name to join on. Default: `unique_id`.

--json supported. Text mode truncates added/removed/changed lists to 10 entries each (with a “…and N more” note); --json returns the full lists.

`diff_config`¶

Show a semantic diff between two config.yaml files: app config, connections, and sources (including field mappings, transforms, and hooks per source).

Usage:

oaa diff_config --config_file=./config.yaml --compare_file=./config-v2.yaml

Argument	Type	Required	Description
`config_file`	`string`	Yes	Path to the first (base) config file.
`compare_file`	`string`	Yes	Path to the second (comparison) config file.

--json supported. In text mode, exits 0 if the configs are identical and exits 1 if they differ; with --json, returns the data (including an identical flag) without exiting.

CLI Commands Reference¶

Core Commands¶

validate_config¶

explode_config¶

version¶

show_sample¶

Introspection Commands¶

list_transforms¶

list_entity_types¶

show_entity¶

list_hooks¶

config_schema¶

Data Inspection Commands¶

test_transform¶

check_env¶

preview¶

preview_mapped¶

validate_mappings¶

Scaffolding Commands¶

init¶

generate_source¶

generate_hook¶

assemble_fragments¶

Analysis & Review Commands¶

validate_payload¶

validate_integration¶

review¶

parse_errors¶

parse_spec¶

Data Safety Commands¶

anonymize¶

Veza API Commands¶

list_providers¶

list_datasources¶

show_provider¶

provider_status¶

delete_provider¶

show_datasource¶

delete_datasource¶

rename_provider¶

export_provider¶

Query & Diff Commands¶

download_query¶

run_query¶

compare_queries¶

diff_config¶

See Also¶

`validate_config`¶

`explode_config`¶

`version`¶

`show_sample`¶

`list_transforms`¶

`list_entity_types`¶

`show_entity`¶

`list_hooks`¶

`config_schema`¶

`test_transform`¶

`check_env`¶

`preview`¶

`preview_mapped`¶

`validate_mappings`¶

`init`¶

`generate_source`¶

`generate_hook`¶

`assemble_fragments`¶

`validate_payload`¶

`validate_integration`¶

`review`¶

`parse_errors`¶

`parse_spec`¶

`anonymize`¶

`list_providers`¶

`list_datasources`¶

`show_provider`¶

`provider_status`¶

`delete_provider`¶

`show_datasource`¶

`delete_datasource`¶

`rename_provider`¶

`export_provider`¶

`download_query`¶

`run_query`¶

`compare_queries`¶

`diff_config`¶