Skip to content

CLI Commands

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

Metaxy - Feature Metadata Management

Table of Contents

Usage:

$ metaxy COMMAND

Arguments:

Options:

  • --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]

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.

metaxy shell

Start interactive shell.

Usage:

$ shell

metaxy migrations

Metadata migration commands

Usage:

$ migrations COMMAND

Commands:

  • apply: Apply migration(s) from YAML files.
  • describe: Show verbose description of migration(s).
  • explain: Show detailed diff for a migration.
  • generate: Generate migration from detected feature changes.
  • list: List all migrations in chain order as defined in code.
  • status: Show migration chain and execution status.

metaxy migrations generate

Generate migration from detected feature changes.

Compares the latest snapshot in the store (or specified from_snapshot) with the current active graph to detect changes.

The migration is recorded in the system tables (not a YAML file).

Usage:

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

Arguments:

  • --OP: Operation class path to use (can be repeated). Example: metaxy.migrations.ops.DataVersionReconciliation [required]

Options:

  • --name: Migration name (creates {timestamp}_{name} ID)
  • --store: Store name (defaults to default)
  • --from-snapshot: Compare from this historical snapshot version (defaults to latest)

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).

Usage:

$ metaxy migrations apply [OPTIONS] [ARGS]

Options:

  • 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 migration chain and execution status.

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

Usage:

$ 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.

Usage:

$ 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.

Usage:

$ metaxy migrations explain [ARGS]

Options:

  • 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

Usage:

$ metaxy migrations describe [ARGS]

Options:

  • 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

Usage:

$ graph COMMAND

Commands:

  • describe: Describe a graph snapshot.
  • history: Show history of recorded graph snapshots.
  • push: Record all feature versions (push graph snapshot).
  • render: Render feature graph visualization.

metaxy graph push

Record all feature versions (push graph snapshot).

Records all features in the active graph to the metadata store with a deterministic snapshot version. This should be run after deploying new feature definitions.

Usage:

$ metaxy graph push [ARGS]

Options:

  • STORE, --store: Metadata store to use (defaults to configured default store)

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.

Usage:

$ metaxy graph history [ARGS]

Options:

  • 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)

Usage:

$ metaxy graph describe [ARGS]

Options:

  • 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

Usage:

$ metaxy graph render [ARGS]

Options:

  • SHOW-FIELDS, --show-fields, --no-show-fields: Show field-level details within features [default: --show-fields]
  • SHOW-FEATURE-VERSIONS, --show-feature-versions, --no-show-feature-versions: Show feature version hashes [default: --show-feature-versions]
  • SHOW-FIELD-VERSIONS, --show-field-versions, --no-show-field-versions: Show field version hashes (requires --show-fields) [default: --show-field-versions]
  • SHOW-CODE-VERSIONS, --show-code-versions, --no-show-code-versions: Show feature and field code versions [default: --no-show-code-versions]
  • SHOW-SNAPSHOT-VERSION, --show-snapshot-version, --no-show-snapshot-version: Show graph snapshot version in output [default: --show-snapshot-version]
  • HASH-LENGTH, --hash-length: Number of characters to show for version hashes (0 for full) [default: 8]
  • DIRECTION, --direction: Graph layout direction: TB (top-bottom) or LR (left-right) [default: TB]
  • FEATURE, --feature: Focus on a specific feature (e.g., 'video/files' or 'video__files')
  • UP, --up: Number of dependency levels to render upstream (default: all)
  • DOWN, --down: Number of dependency levels to render downstream (default: all)
  • PROJECT, --project: Filter nodes by project (show only features from this project)
  • SHOW-PROJECTS, --show-projects, --no-show-projects: Show project names in feature nodes [default: --show-projects]
  • -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: Snapshot version to render (default: current graph from code)
  • STORE, --store: Metadata store to use (for loading historical snapshots)
  • MINIMAL, --minimal, --no-minimal: Minimal output: only feature keys and dependencies [default: --no-minimal]
  • VERBOSE, --verbose, --no-verbose: Verbose output: show all available information [default: --no-verbose]

metaxy graph-diff

Compare and visualize graph snapshots

Usage:

$ graph-diff COMMAND

Commands:

  • render: Render merged graph visualization comparing two 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

Usage:

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

Arguments:

  • FROM-SNAPSHOT: First snapshot to compare (can be "latest", "current", or snapshot hash) [required]

Options:

  • 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)
  • SHOW-FIELDS, --show-fields, --no-show-fields: Show field-level details within features [default: --show-fields]
  • SHOW-FEATURE-VERSIONS, --show-feature-versions, --no-show-feature-versions: Show feature version hashes [default: --show-feature-versions]
  • SHOW-FIELD-VERSIONS, --show-field-versions, --no-show-field-versions: Show field version hashes (requires --show-fields) [default: --show-field-versions]
  • SHOW-CODE-VERSIONS, --show-code-versions, --no-show-code-versions: Show feature and field code versions [default: --no-show-code-versions]
  • SHOW-SNAPSHOT-VERSION, --show-snapshot-version, --no-show-snapshot-version: Show graph snapshot version in output [default: --show-snapshot-version]
  • HASH-LENGTH, --hash-length: Number of characters to show for version hashes (0 for full) [default: 8]
  • DIRECTION, --direction: Graph layout direction: TB (top-bottom) or LR (left-right) [default: TB]
  • FEATURE, --feature: Focus on a specific feature (e.g., 'video/files' or 'video__files')
  • UP, --up: Number of dependency levels to render upstream (default: all)
  • DOWN, --down: Number of dependency levels to render downstream (default: all)
  • PROJECT, --project: Filter nodes by project (show only features from this project)
  • SHOW-PROJECTS, --show-projects, --no-show-projects: Show project names in feature nodes [default: --show-projects]
  • MINIMAL, --minimal, --no-minimal: Minimal output: only feature keys and dependencies [default: --no-minimal]
  • VERBOSE, --verbose, --no-verbose: Verbose output: show all available information [default: --no-verbose]

metaxy list

List Metaxy entities

Usage:

$ list COMMAND

Commands:

  • features: List Metaxy features.

metaxy list features

List Metaxy features.

Usage:

$ metaxy list features

metaxy metadata

Manage Metaxy metadata

Usage:

$ metadata COMMAND

Commands:

  • copy: Copy metadata between stores.
  • drop: Drop metadata from a store.

metaxy metadata copy

Copy metadata between stores.

Copies metadata for specified features from one store to another, optionally using a historical version. Useful for: - Migrating data between environments - Backfilling metadata - Copying specific feature versions

Incremental Mode (default): By default, performs an anti-join on sample_uid to skip rows that already exist in the destination for the same snapshot_version. This prevents duplicate writes. Disabling incremental (--no-incremental) may improve performance when: - The destination store is empty or has no overlap with source - The destination store has eventual deduplication

Usage:

$ metaxy metadata copy FROM TO [ARGS]

Arguments:

  • FROM: Source store name (must be configured in metaxy.toml) [required]
  • TO: Destination store name (must be configured in metaxy.toml) [required]

Options:

  • FEATURE, --feature, --empty-feature: Feature key to copy (e.g., 'my_feature' or 'group/my_feature'). Can be repeated multiple times. If not specified, uses --all-features.
  • ALL-FEATURES, --all-features, --no-all-features: Copy all features from source store [default: --no-all-features]
  • SNAPSHOT, --snapshot: Snapshot version to copy (defaults to latest in source store). The snapshot_version is preserved in the destination.
  • INCREMENTAL, --incremental, --no-incremental: Use incremental copy (compare provenance_by_field to skip existing rows). Disable for better performance if destination is empty or uses deduplication. [default: --incremental]

metaxy metadata drop

Drop metadata from a store.

Removes metadata for specified features from the store. This is a destructive operation and requires --confirm flag.

Useful for: - Cleaning up test data - Re-computing feature metadata from scratch - Removing obsolete features

Usage:

$ metaxy metadata drop [ARGS]

Options:

  • STORE, --store: Store name to drop metadata from (defaults to configured default store)
  • FEATURE, --feature, --empty-feature: Feature key to drop (e.g., 'my_feature' or 'group/my_feature'). Can be repeated multiple times. If not specified, uses --all-features.
  • ALL-FEATURES, --all-features, --no-all-features: Drop metadata for all features in the store [default: --no-all-features]
  • CONFIRM, --confirm, --no-confirm: Confirm the drop operation (required to prevent accidental deletion) [default: --no-confirm]

Examples

Recording a graph snapshot

# Push the current feature graph to the metadata store
metaxy graph push

The recommendation is to run this command in your CD pipeline.

Generating and applying migrations

# Generate a migration for detected changes
metaxy migrations generate --op metaxy.migrations.ops.DataVersionReconciliation

# Apply pending migrations
metaxy migrations apply

Visualizing the feature graph

# Render as terminal tree view
metaxy graph render

# Render as Mermaid diagram
metaxy graph render --format mermaid

# Compare two snapshots
metaxy graph-diff render <snapshot-id> current --format mermaid