Skip to content

CLI Commands

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

Warning

The CLI is not stable yet.

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:

Global:

  • --config-file: Path to the Metaxy configuration file. Defaults to auto-discovery. [env: METAXY_CONFIG_FILE]
  • --project: Metaxy project to work with. Some commands may forbid setting this argument. [env: METAXY_PROJECT]
  • --all-projects, --no-all-projects: Operate on all available Metaxy projects. Some commands may forbid setting this argument. [env: METAXY_ALL_PROJECTS] [default: False]
  • --sync, --no-sync: Load external feature definitions from the metadata store before executing the command. [env: METAXY_SYNC] [default: False]
  • --locked, --no-locked: When used with --sync, raise an error if external feature versions don't match the actual versions from the metadata store. [env: METAXY_LOCKED] [default: False]

metaxy shell

metaxy shell

Start interactive shell.

Global:

  • --config-file: Path to the Metaxy configuration file. Defaults to auto-discovery. [env: METAXY_CONFIG_FILE]
  • --project: Metaxy project to work with. Some commands may forbid setting this argument. [env: METAXY_PROJECT]
  • --all-projects, --no-all-projects: Operate on all available Metaxy projects. Some commands may forbid setting this argument. [env: METAXY_ALL_PROJECTS] [default: False]
  • --sync, --no-sync: Load external feature definitions from the metadata store before executing the command. [env: METAXY_SYNC] [default: False]
  • --locked, --no-locked: When used with --sync, raise an error if external feature versions don't match the actual versions from the metadata store. [env: METAXY_LOCKED] [default: False]

metaxy config

Manage Metaxy configuration

Global:

  • --config-file: Path to the Metaxy configuration file. Defaults to auto-discovery. [env: METAXY_CONFIG_FILE]
  • --project: Metaxy project to work with. Some commands may forbid setting this argument. [env: METAXY_PROJECT]
  • --all-projects, --no-all-projects: Operate on all available Metaxy projects. Some commands may forbid setting this argument. [env: METAXY_ALL_PROJECTS] [default: False]
  • --sync, --no-sync: Load external feature definitions from the metadata store before executing the command. [env: METAXY_SYNC] [default: False]
  • --locked, --no-locked: When used with --sync, raise an error if external feature versions don't match the actual versions from the metadata store. [env: METAXY_LOCKED] [default: False]

metaxy config print

metaxy config print [OPTIONS]

Print the current Metaxy configuration.

Parameters:

  • --format, -f: Output format: 'toml' (with syntax highlighting) or 'json'. [choices: toml, json] [default: toml]

metaxy describe

Describe Metaxy entities in detail

Global:

  • --config-file: Path to the Metaxy configuration file. Defaults to auto-discovery. [env: METAXY_CONFIG_FILE]
  • --project: Metaxy project to work with. Some commands may forbid setting this argument. [env: METAXY_PROJECT]
  • --all-projects, --no-all-projects: Operate on all available Metaxy projects. Some commands may forbid setting this argument. [env: METAXY_ALL_PROJECTS] [default: False]
  • --sync, --no-sync: Load external feature definitions from the metadata store before executing the command. [env: METAXY_SYNC] [default: False]
  • --locked, --no-locked: When used with --sync, raise an error if external feature versions don't match the actual versions from the metadata store. [env: METAXY_LOCKED] [default: False]

metaxy describe graph

metaxy describe graph [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 there some features are defined in different projects)

Parameters:

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

metaxy describe features

metaxy describe features [OPTIONS] [ARGS]

Describe one or more features in detail.

Shows comprehensive information about features including project, key, version, description, fields with their versions and dependencies.

Parameters:

  • --format, -f: Output format: 'plain' (default) or 'json'. [choices: plain, json] [default: plain]

Feature Selection:

  • FEATURES, --features, --empty-features: Feature keys (e.g., 'my_feature' or 'namespace/feature'). [default: ()]
  • ALL-FEATURES, --all-features, --no-all-features: Apply to all features in the project's feature graph. [default: False]

metaxy graph

Manage feature graphs

Global:

  • --config-file: Path to the Metaxy configuration file. Defaults to auto-discovery. [env: METAXY_CONFIG_FILE]
  • --project: Metaxy project to work with. Some commands may forbid setting this argument. [env: METAXY_PROJECT]
  • --all-projects, --no-all-projects: Operate on all available Metaxy projects. Some commands may forbid setting this argument. [env: METAXY_ALL_PROJECTS] [default: False]
  • --sync, --no-sync: Load external feature definitions from the metadata store before executing the command. [env: METAXY_SYNC] [default: False]
  • --locked, --no-locked: When used with --sync, raise an error if external feature versions don't match the actual versions from the metadata store. [env: METAXY_LOCKED] [default: False]

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: Project 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-project-version, --no-show-project-version: Show graph project 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]
  • --title: Custom title for the graph. Defaults to 'Feature Graph' or 'Feature Graph Changes' for diffs.

metaxy history

metaxy history [ARGS]

Show history of recorded graph snapshots from the metadata store.

Parameters:

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

Global:

  • --config-file: Path to the Metaxy configuration file. Defaults to auto-discovery. [env: METAXY_CONFIG_FILE]
  • --project: Metaxy project to work with. Some commands may forbid setting this argument. [env: METAXY_PROJECT]
  • --all-projects, --no-all-projects: Operate on all available Metaxy projects. Some commands may forbid setting this argument. [env: METAXY_ALL_PROJECTS] [default: False]
  • --sync, --no-sync: Load external feature definitions from the metadata store before executing the command. [env: METAXY_SYNC] [default: False]
  • --locked, --no-locked: When used with --sync, raise an error if external feature versions don't match the actual versions from the metadata store. [env: METAXY_LOCKED] [default: False]

metaxy list

List Metaxy entities

Global:

  • --config-file: Path to the Metaxy configuration file. Defaults to auto-discovery. [env: METAXY_CONFIG_FILE]
  • --project: Metaxy project to work with. Some commands may forbid setting this argument. [env: METAXY_PROJECT]
  • --all-projects, --no-all-projects: Operate on all available Metaxy projects. Some commands may forbid setting this argument. [env: METAXY_ALL_PROJECTS] [default: False]
  • --sync, --no-sync: Load external feature definitions from the metadata store before executing the command. [env: METAXY_SYNC] [default: False]
  • --locked, --no-locked: When used with --sync, raise an error if external feature versions don't match the actual versions from the metadata store. [env: METAXY_LOCKED] [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 list stores

metaxy list stores [OPTIONS]

List configured metadata stores.

Parameters:

  • --format, -f: Output format: 'plain' (default) or 'json'. [choices: plain, json] [default: plain]

metaxy metadata

Manage Metaxy metadata in metadata stores.

Global:

  • --config-file: Path to the Metaxy configuration file. Defaults to auto-discovery. [env: METAXY_CONFIG_FILE]
  • --project: Metaxy project to work with. Some commands may forbid setting this argument. [env: METAXY_PROJECT]
  • --all-projects, --no-all-projects: Operate on all available Metaxy projects. Some commands may forbid setting this argument. [env: METAXY_ALL_PROJECTS] [default: False]
  • --sync, --no-sync: Load external feature definitions from the metadata store before executing the command. [env: METAXY_SYNC] [default: False]
  • --locked, --no-locked: When used with --sync, raise an error if external feature versions don't match the actual versions from the metadata store. [env: METAXY_LOCKED] [default: False]

metaxy metadata status

metaxy metadata status [OPTIONS] [ARGS]

Check metadata completeness and freshness for specified features.

Parameters:

  • --store: Metadata store name (defaults to configured default store).
  • --filter, --empty-filter: SQL WHERE clause filter applied to the result of the status increment. Can be repeated.
  • --global-filter, --empty-global-filter: SQL WHERE clause filter applied to all features being selected (including upstream). Can be repeated.
  • --stale-if, --empty-stale-if: SQL WHERE clause predicate that marks matching records as stale regardless of version. Can be repeated.
  • --snapshot-id: Check metadata against a specific project 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]

Feature Selection:

  • FEATURES, --features, --empty-features: Feature keys (e.g., 'my_feature' or 'namespace/feature'). [default: ()]
  • ALL-FEATURES, --all-features, --no-all-features: Apply to all features in the project's feature graph. [default: False]

metaxy metadata delete

metaxy metadata delete [OPTIONS] [ARGS]

Delete metadata rows matching filters.

Parameters:

  • --store: Metadata store name (defaults to configured default store).
  • --filter, --empty-filter: SQL WHERE clause filter applied to the result of the status increment. Can be repeated.
  • --soft, --hard: Whether to mark records with deletion timestamps vs physically remove them. [default: True]
  • --with-feature-history, --no-with-feature-history: Include rows from all historical feature versions (by default, only current version is affected). [default: False]
  • --yes, --no-yes: Confirm deletion without prompting (required for hard deletes without filters). [default: False]
  • --dry-run, --no-dry-run: Preview deletion: show features, filters, and row counts without executing. [default: False]

Feature Selection:

  • FEATURES, --features, --empty-features: Feature keys (e.g., 'my_feature' or 'namespace/feature'). [default: ()]
  • ALL-FEATURES, --all-features, --no-all-features: Apply to all features in the project's feature graph. [default: False]

metaxy metadata rebase

metaxy metadata rebase --from STR [OPTIONS] FEATURE

Rebase metadata from one feature version to another, recalculating provenance.

Parameters:

  • FEATURE, --feature: Feature key to rebase. [required]
  • --from: Source feature version hash. [required]
  • --to: Target feature version hash. Defaults to the current feature version.
  • --store: Metadata store name (defaults to configured default store).
  • --dry-run, --no-dry-run: Preview without executing. [default: False]

metaxy metadata copy

metaxy metadata copy --from STR --to STR [OPTIONS] [ARGS]

Copy metadata from one store to another.

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

Parameters:

  • --from: Source store name to copy metadata from. [required]
  • --to: Destination store name to copy metadata to. [required]
  • --filter, --empty-filter: SQL WHERE clause filter applied to the result of the status increment. Can be repeated.
  • --with-feature-history, --no-with-feature-history: Include rows from all historical feature versions (by default, only current version is copied). [default: True]
  • --with-sample-history, --no-with-sample-history: Include all historical materializations per sample (by default, deduplicates by id_columns). [default: False]

Feature Selection:

  • FEATURES, --features, --empty-features: Feature keys (e.g., 'my_feature' or 'namespace/feature'). [default: ()]
  • ALL-FEATURES, --all-features, --no-all-features: Apply to all features in the project's feature graph. [default: False]

metaxy mcp

metaxy mcp

MCP server commands.

Global:

  • --config-file: Path to the Metaxy configuration file. Defaults to auto-discovery. [env: METAXY_CONFIG_FILE]
  • --project: Metaxy project to work with. Some commands may forbid setting this argument. [env: METAXY_PROJECT]
  • --all-projects, --no-all-projects: Operate on all available Metaxy projects. Some commands may forbid setting this argument. [env: METAXY_ALL_PROJECTS] [default: False]
  • --sync, --no-sync: Load external feature definitions from the metadata store before executing the command. [env: METAXY_SYNC] [default: False]
  • --locked, --no-locked: When used with --sync, raise an error if external feature versions don't match the actual versions from the metadata store. [env: METAXY_LOCKED] [default: False]

metaxy push

metaxy push [OPTIONS] [ARGS]

Push feature definitions to the metadata store

Parameters:

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

Global:

  • --config-file: Path to the Metaxy configuration file. Defaults to auto-discovery. [env: METAXY_CONFIG_FILE]
  • --project: Metaxy project to work with. Some commands may forbid setting this argument. [env: METAXY_PROJECT]
  • --all-projects, --no-all-projects: Operate on all available Metaxy projects. Some commands may forbid setting this argument. [env: METAXY_ALL_PROJECTS] [default: False]
  • --sync, --no-sync: Load external feature definitions from the metadata store before executing the command. [env: METAXY_SYNC] [default: False]
  • --locked, --no-locked: When used with --sync, raise an error if external feature versions don't match the actual versions from the metadata store. [env: METAXY_LOCKED] [default: False]

metaxy lock

metaxy lock [OPTIONS] [ARGS]

Generate metaxy.lock file with external feature definitions fetched from the metadata store.

Analyzes the current feature graph to find external dependencies, then fetches those feature definitions (and their transitive dependencies) from the metadata store.

Distribution entry points are automatically filtered to only load features from the current project and its Python dependencies (including transitive), preventing unrelated packages from polluting the lock file.

This functionality is currently experimental.

Parameters:

  • STORE, --store: Metadata store to use (defaults to configured default store) [env: METAXY_STORE]
  • --output, -o: Output file path (defaults to metaxy.lock in config directory) [env: METAXY_OUTPUT] [default: ""]

Global:

  • --config-file: Path to the Metaxy configuration file. Defaults to auto-discovery. [env: METAXY_CONFIG_FILE]
  • --project: Metaxy project to work with. Some commands may forbid setting this argument. [env: METAXY_PROJECT]
  • --all-projects, --no-all-projects: Operate on all available Metaxy projects. Some commands may forbid setting this argument. [env: METAXY_ALL_PROJECTS] [default: False]
  • --sync, --no-sync: Load external feature definitions from the metadata store before executing the command. [env: METAXY_SYNC] [default: False]
  • --locked, --no-locked: When used with --sync, raise an error if external feature versions don't match the actual versions from the metadata store. [env: METAXY_LOCKED] [default: False]