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:

  • config: Manage Metaxy configuration
  • describe: Describe Metaxy entities in detail
  • graph: Manage feature graphs
  • list: List Metaxy entities
  • lock: Generate metaxy.lock file with external feature definitions fetched from the metadata store.
  • mcp: MCP server commands.
  • metadata: Manage Metaxy metadata in metadata stores.
  • push: Push feature definitions to the metadata store
  • 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 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 history

metaxy graph history [ARGS]

Show history of recorded graph snapshots.

Displays all recorded graph snapshots from the metadata store, showing project 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 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 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.
  • --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 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.

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]