Skip to content

CLI Commands

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

Warning

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

metaxy COMMAND

Metaxy CLI.

Auto-discovers configuration (metaxy.toml or pyproject.toml) in current or parent directories. Feature definitions are collected via feature discovery. Supports loading environment variables from a .env file in the current directory.

Table of Contents

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.

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: False]

metaxy shell

metaxy shell

Start interactive shell.

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: False]

metaxy migrations

Metadata migration commands

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: False]

metaxy migrations generate

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

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.

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, --empty-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

metaxy migrations apply [OPTIONS] [ARGS]

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

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: False]
  • --rerun, --no-rerun: Re-run all steps, including already completed ones [default: False]

metaxy migrations status

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 list

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 explain

metaxy migrations explain [ARGS]

Show detailed diff for a migration.

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

Parameters:

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

metaxy migrations describe

metaxy migrations describe [ARGS]

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

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

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: False]

metaxy graph push

metaxy graph push [OPTIONS] [ARGS]

Serialize all Metaxy features to the metadata store.

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

Parameters:

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

metaxy graph history

metaxy graph history [ARGS]

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.

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

metaxy graph describe [ARGS]

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)

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

metaxy graph render [OPTIONS] [ARGS]

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

Parameters:

  • --format, -f: Output format: terminal, mermaid, or graphviz [default: terminal]
  • --type, -t: Terminal rendering type: graph or cards (only for --format terminal) [choices: graph, cards] [default: graph]
  • --output, -o: 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: False]
  • --verbose, --no-verbose: Verbose output: show all available information [default: False]
  • --show-fields, --no-show-fields: Show field-level details within features [default: True]
  • --show-feature-versions, --no-show-feature-versions: Show feature version hashes [default: True]
  • --show-field-versions, --no-show-field-versions: Show field version hashes (requires --show-fields) [default: True]
  • --show-code-versions, --no-show-code-versions: Show feature and field code versions [default: False]
  • --show-snapshot-version, --no-show-snapshot-version: Show graph snapshot version in output [default: True]
  • --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: True]

metaxy graph-diff

Compare and visualize graph snapshots

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: False]

metaxy graph-diff render

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

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

Parameters:

  • FROM-SNAPSHOT, --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)
  • --format, -f: Output format: terminal, cards, mermaid, graphviz, json, or yaml [choices: terminal, cards, mermaid, graphviz, json, yaml] [default: terminal]
  • --output, -o: Output file path (default: stdout)
  • --minimal, --no-minimal: Minimal output: only feature keys and dependencies [default: False]
  • --verbose, --no-verbose: Verbose output: show all available information [default: False]
  • --show-fields, --no-show-fields: Show field-level details within features [default: True]
  • --show-feature-versions, --no-show-feature-versions: Show feature version hashes [default: True]
  • --show-field-versions, --no-show-field-versions: Show field version hashes (requires --show-fields) [default: True]
  • --show-code-versions, --no-show-code-versions: Show feature and field code versions [default: False]
  • --show-snapshot-version, --no-show-snapshot-version: Show graph snapshot version in output [default: True]
  • --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: True]

metaxy list

List Metaxy entities

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: False]

metaxy list features

metaxy list features [OPTIONS]

List Metaxy features in the current project.

Parameters:

  • --verbose, --no-verbose, -v: Show detailed information including field dependencies and versions. [default: False]
  • --format, -f: Output format: 'plain' (default) or 'json'. [choices: plain, json] [default: plain]

metaxy metadata

Manage Metaxy metadata

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: False]

metaxy metadata status

metaxy metadata status [OPTIONS]

Check metadata completeness and freshness for specified features.

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: False]
  • --store: Metadata store name (defaults to configured default store).
  • --filter, --empty-filter: SQL WHERE clause filter applied to all features. Can be repeated.
  • --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: False]
  • --verbose, --no-verbose: Whether to display sample slices of dataframes. [default: False]
  • --progress, --no-progress: Display progress percentage showing how many input units have been processed at least once. Stale samples are counted as processed. [default: False]
  • --allow-fallback-stores, --no-allow-fallback-stores: Whether to read metadata from fallback stores. [default: True]
  • --format: [choices: plain, json] [default: plain]

metaxy metadata drop

metaxy metadata drop [OPTIONS]

Drop metadata from a store.

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

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: False]
  • --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: False]
  • --format: Output format: 'plain' (default) or 'json'. [choices: plain, json] [default: plain]

metaxy metadata copy

metaxy metadata copy [OPTIONS] FROM TO [ARGS...]

Copy metadata from one store to another.

Copies metadata for specified features from source to destination store. By default, copies all versions (--no-current-only) and deduplicates by keeping only the latest row per sample (--latest-only).

Arguments:

  • FEATURES: One or more feature keys to copy, separated by whitespaces.

Parameters:

  • FROM, --from: Source store name to copy metadata from. [required]
  • TO, --to: Destination store name to copy metadata to. [required]
  • --filter, --empty-filter: SQL WHERE clause filter applied to all features. Can be repeated.
  • --current-only, --no-current-only: Only copy rows with the current feature_version (as defined in loaded feature graph). [default: False]
  • --latest-only, --no-latest-only: Deduplicate samples by keeping only the latest row per id_columns group. [default: True]