CLI Commands

This section provides a comprehensive reference for all Metaxy CLI commands.

Warning

Some CLI commands are experimental (read: half-baked)

Metaxy CLI.

Auto-discovers configuration (metaxy.toml or pyproject.toml) in current or parent directories. Feature definitions are collected via feature discovery.

Table of Contents

• shell
• migrations
  • generate
  • apply
  • status
  • list
  • explain
  • describe
• graph
  • push
  • history
  • describe
  • render
• graph-diff
  • render
• list
  • features
• metadata
  • status
  • drop

metaxy COMMAND

Commands:

• graph: Manage feature graphs
• graph-diff: Compare and visualize graph snapshots
• list: List Metaxy entities
• metadata: Manage Metaxy metadata
• migrations: Metadata migration commands
• shell: Start interactive shell.

Arguments:

Parameters:

• --config-file: Global option. Path to the Metaxy configuration file. Defaults to auto-discovery. [env: METAXY_CONFIG_FILE]
• --project: Global option. Metaxy project to work with. Some commands may forbid setting this argument. [env: METAXY_PROJECT]
• --all-projects, --no-all-projects: Global option. Operate on all available Metaxy projects. Some commands may forbid setting this argument. [env: METAXY_ALL_PROJECTS] [default: --no-all-projects]

metaxy shell

Start interactive shell.

metaxy shell

metaxy migrations

Metadata migration commands

metaxy migrations generate

Generate migration from detected feature changes.

Two migration types are supported:

• diff : Compares the latest snapshot in the store (or specified from_snapshot) with the current active graph to detect changes. Only affected features are included.

• full: Creates a migration that includes ALL features in the current graph. Each operation will have a 'features' list with all feature keys.

metaxy migrations generate --op LIST[STR] [OPTIONS]

Parameters:

• --name: Migration name (creates {timestamp}_{name} ID)
• --store: Store name (defaults to default)
• --from-snapshot: Compare from this historical snapshot version (defaults to latest)
• --OP: Operation class path to use (can be repeated). Example: metaxy.migrations.ops.DataVersionReconciliation [required]
• --type: Migration type: 'diff' (compare different graph snapshots) or 'full' (operates on a single graph snapshot) [choices: diff, full] [default: diff]

metaxy migrations apply

Apply migration(s) from YAML files.

Reads migration definitions from .metaxy/migrations/ directory (git). Follows parent chain to ensure correct order. Tracks execution state in database (events).

metaxy migrations apply [OPTIONS] [ARGS]

Parameters:

• MIGRATION-ID, --migration-id: Migration ID to apply (applies all unapplied if not specified)
• STORE, --store: Metadata store to use.
• --dry-run, --no-dry-run: Preview changes without executing [default: --no-dry-run]

metaxy migrations status

Show migrations and execution status.

Reads migration definitions from YAML files (git). Shows execution status from database events. Displays the parent chain in order.

metaxy migrations status

metaxy migrations list

List all migrations in chain order as defined in code.

Displays a simple table showing migration ID, creation time, and operations.

metaxy migrations list

metaxy migrations explain

Show detailed diff for a migration.

Reads migration from YAML file. Computes and displays the GraphDiff between the two snapshots on-demand.

metaxy migrations explain [ARGS]

Parameters:

• MIGRATION-ID, --migration-id: Migration ID to explain (explains latest if not specified)

metaxy migrations describe

Show verbose description of migration(s).

Displays detailed information about what the migration will do: - Migration metadata (ID, parent, snapshots, created timestamp) - Operations to execute - Affected features with row counts - Execution status if already run

metaxy migrations describe [ARGS]

Parameters:

• MIGRATION-IDS, --migration-ids, --empty-migration-ids: Migration IDs to describe (default: all migrations in order) [default: []]
• STORE, --store: Metadata store to use.

metaxy graph

Manage feature graphs

metaxy graph push

Serialize all Metaxy features to the metadata store.

This is intended to be invoked in a CD pipeline before running Metaxy code in production.

metaxy graph push [OPTIONS] [ARGS]

Parameters:

• STORE, --store: Metadata store to use (defaults to configured default store)
• -t, --tags: Arbitrary key-value pairs to attach to the pushed snapshot. Example: --tags.git_commit abc123def.

metaxy graph history

Show history of recorded graph snapshots.

Displays all recorded graph snapshots from the metadata store, showing snapshot versions, when they were recorded, and feature counts.

metaxy graph history [ARGS]

Parameters:

• STORE, --store: Metadata store to use (defaults to configured default store)
• LIMIT, --limit: Limit number of snapshots to show (defaults to all)

metaxy graph describe

Describe a graph snapshot.

Shows detailed information about a graph snapshot including: - Feature count (optionally filtered by project) - Graph depth (longest dependency chain) - Root features (features with no dependencies) - Leaf features (features with no dependents) - Project breakdown (if multi-project)

metaxy graph describe [ARGS]

Parameters:

• SNAPSHOT, --snapshot: Snapshot version to describe (defaults to current graph from code)
• STORE, --store: Metadata store to use (defaults to configured default store)

metaxy graph render

Render feature graph visualization.

Visualize the feature graph in different formats: - terminal: Terminal rendering with two types: - graph (default): Hierarchical tree view - cards: Panel/card-based view with dependency edges - mermaid: Mermaid flowchart markup - graphviz: Graphviz DOT format

metaxy graph render [OPTIONS] [ARGS]

Parameters:

• -f, --format: Output format: terminal, mermaid, or graphviz [default: terminal]
• -t, --type: Terminal rendering type: graph or cards (only for --format terminal) [choices: graph, cards] [default: graph]
• -o, --output: Output file path (default: stdout)
• --snapshot: Snapshot version to render (default: current graph from code)
• --store: Metadata store to use (for loading historical snapshots)
• --minimal, --no-minimal: Minimal output: only feature keys and dependencies [default: --no-minimal]
• --verbose, --no-verbose: Verbose output: show all available information [default: --no-verbose]
• --show-fields, --no-show-fields: Show field-level details within features [default: --show-fields]
• --show-feature-versions, --no-show-feature-versions: Show feature version hashes [default: --show-feature-versions]
• --show-field-versions, --no-show-field-versions: Show field version hashes (requires --show-fields) [default: --show-field-versions]
• --show-code-versions, --no-show-code-versions: Show feature and field code versions [default: --no-show-code-versions]
• --show-snapshot-version, --no-show-snapshot-version: Show graph snapshot version in output [default: --show-snapshot-version]
• --hash-length: Number of characters to show for version hashes (0 for full) [default: 8]
• --direction: Graph layout direction: TB (top-bottom) or LR (left-right) [default: TB]
• --feature: Focus on a specific feature (e.g., 'video/files' or 'video__files')
• --up: Number of dependency levels to render upstream (default: all)
• --down: Number of dependency levels to render downstream (default: all)
• --project: Filter nodes by project (show only features from this project)
• --show-projects, --no-show-projects: Show project names in feature nodes [default: --show-projects]

metaxy graph-diff

Compare and visualize graph snapshots

metaxy graph-diff render

Render merged graph visualization comparing two snapshots.

Shows all features color-coded by status (added/removed/changed/unchanged). Uses the unified rendering system - same renderers as 'metaxy graph render'.

Special snapshot literals: - "latest": Most recent snapshot in the store - "current": Current graph state from code

Output formats: - terminal: Hierarchical tree view (default) - cards: Panel/card-based view - mermaid: Mermaid flowchart diagram - graphviz: Graphviz DOT format

metaxy graph-diff render [OPTIONS] FROM-SNAPSHOT [ARGS]

Parameters:

• FROM-SNAPSHOT: First snapshot to compare (can be "latest", "current", or snapshot hash) [required]
• TO-SNAPSHOT, --to-snapshot: Second snapshot to compare (can be "latest", "current", or snapshot hash) [default: current]
• STORE, --store: Metadata store to use (defaults to configured default store)
• -f, --format: Output format: terminal, cards, mermaid, graphviz, json, or yaml [choices: terminal, cards, mermaid, graphviz, json, yaml] [default: terminal]
• -o, --output: Output file path (default: stdout)
• --minimal, --no-minimal: Minimal output: only feature keys and dependencies [default: --no-minimal]
• --verbose, --no-verbose: Verbose output: show all available information [default: --no-verbose]
• --show-fields, --no-show-fields: Show field-level details within features [default: --show-fields]
• --show-feature-versions, --no-show-feature-versions: Show feature version hashes [default: --show-feature-versions]
• --show-field-versions, --no-show-field-versions: Show field version hashes (requires --show-fields) [default: --show-field-versions]
• --show-code-versions, --no-show-code-versions: Show feature and field code versions [default: --no-show-code-versions]
• --show-snapshot-version, --no-show-snapshot-version: Show graph snapshot version in output [default: --show-snapshot-version]
• --hash-length: Number of characters to show for version hashes (0 for full) [default: 8]
• --direction: Graph layout direction: TB (top-bottom) or LR (left-right) [default: TB]
• --feature: Focus on a specific feature (e.g., 'video/files' or 'video__files')
• --up: Number of dependency levels to render upstream (default: all)
• --down: Number of dependency levels to render downstream (default: all)
• --project: Filter nodes by project (show only features from this project)
• --show-projects, --no-show-projects: Show project names in feature nodes [default: --show-projects]

metaxy list

List Metaxy entities

metaxy list features

List Metaxy features.

metaxy list features

metaxy metadata

Manage Metaxy metadata

metaxy metadata status

Check metadata completeness and freshness for specified features.

metaxy metadata status [OPTIONS]

Parameters:

• --feature, --empty-feature: Feature key (e.g., 'my_feature' or 'namespace/feature'). Can be repeated.
• --all-features, --no-all-features: Apply to all features in the project's feature graph. [default: --no-all-features]
• --store: Metadata store name (defaults to configured default store).
• --snapshot-id: Check metadata against a specific snapshot version.
• --assert-in-sync, --no-assert-in-sync: Exit with error if any feature needs updates or metadata is missing. [default: --no-assert-in-sync]
• --verbose, --no-verbose: Show additional details about samples needing updates. [default: --no-verbose]
• --format: [choices: plain, json] [default: plain]

metaxy metadata drop

Drop metadata from a store.

Removes metadata for specified features. This is destructive and requires --confirm.

metaxy metadata drop [OPTIONS]

Parameters:

• --feature, --empty-feature: Feature key (e.g., 'my_feature' or 'namespace/feature'). Can be repeated.
• --all-features, --no-all-features: Apply to all features in the project's feature graph. [default: --no-all-features]
• --store: Store name to drop metadata from (defaults to configured default store).
• --confirm, --no-confirm: Confirm the drop operation (required to prevent accidental deletion). [default: --no-confirm]
• --format: Output format: 'plain' (default) or 'json'. [choices: plain, json] [default: plain]