Skip to content

Pipelex CLI Documentation

The pipelex CLI is the runtime and project-configuration CLI for Pipelex. Use it to initialize config, validate methods, run pipes, inspect the runtime state, and generate supporting files.

Installation

The CLI renders its tables, panels and log lines through Rich, which is the cli extra, so install the package with it:

uv tool install "pipelex[cli]"

The same extra serves the pipelex-agent CLI. A process that only embeds Pipelex, a server for instance, installs the package without it; see Rich Imports for what that process gives up and how the runtime keeps Rich out of it.

Overview

The Pipelex CLI is organized into several command groups:

Command Description
init Initialize Pipelex configuration and choose where your runs execute: the hosted Pipelex API or this machine
login Get a Pipelex API key through your browser, or paste one, and save it for runs on the hosted Pipelex API
update Refresh the model deck and backends/internal.toml to match the installed pipelex version
migrate Bring your configuration files up to the schema the installed version expects
doctor Check configuration health, judged by where your runs execute, and fix what can be fixed
validate Validate configuration and pipelines
fix Apply deterministic safe fixes to a bundle and re-validate
show Inspect configuration, pipes, and AI models
run Execute pipelines, on this machine or on the hosted Pipelex API
run method by address Fetch and run a method straight from a public GitHub repository
build Generate concept structures and example inputs and outputs for a pipe
usage-stats See and change the anonymous usage statistics of every Pipelex tool on the machine

Global flags

These flags work on any pipelex command and are position-agnostic — place them anywhere in the invocation:

  • --traceback - print the full Rich-rendered stack trace before the error panel, both on stderr, and let the log line about an unexpected failure carry its traceback. Off by default, since a traceback prints the text of every exception along the chain, which can quote a run's data; without it the log line names the failure by its code, the classes along its chain and the frames it went through, by module, line and function. Both pipelex run --traceback pipe ... and pipelex run pipe ... --traceback work.
  • --no-logo - suppress the startup logo banner. Handy for clean logs and to save tokens in agent output.

--version / -V is not one of these: it is an option on the root command, so it goes before any subcommand (pipelex --version, never pipelex show --version). See below.

The version handshake

pipelex --version reports three numbers, not one, because a client needs all three to know what it is talking to and they move on independent cadences:

pipelex <runtime version>
mthds-protocol <MTHDS Protocol version>
mthds-standard <MTHDS standard version>
  • pipelex — the installed runtime's own version.
  • mthds-protocol — the version of the MTHDS Protocol this runtime speaks — the request and response shapes of the runner operations.
  • mthds-standard — the version of the MTHDS standard it implements: the language, the native concept set, and what a manifest's mthds_version constraint is evaluated against.

pipelex-agent --version prints the same three lines, with pipelex-agent naming the first.

The shape is a contract rather than presentation: the output is exactly these three lines, each <label> <version>, the labels are stable, and the first line keeps the historical <program> <version> form. It is meant to be read by clients that drive the CLI as a subprocess and turn it into a protocol VersionInfo — a consumer should match on the label rather than on line position, and must not treat the whole of stdout as a single version string.

Package manifest management currently lives in the mthds CLI:

  • package — mthds package init, mthds package list, and mthds package validate

Usage Tips

  1. Initial Setup

    • Run pipelex init to create configuration files and choose where your runs execute
    • On the hosted Pipelex API, pipelex init signs you in for a Pipelex API key; pipelex login does it again on its own
    • On this machine, it asks for your backends and their keys; configure them further in .pipelex/inference/backends.toml

  2. Development Workflow

    • Write or generate pipelines in .mthds files
    • Validate with pipelex validate pipe your_pipe_code or pipelex validate bundle your_bundle.mthds during development
    • When validation errors carry a 💡 Suggested fix: line, apply them automatically with pipelex fix bundle your_bundle.mthds
    • Run pipelex validate pipe --all before committing changes

  3. Running Pipelines

    • Use pipelex show pipe --all to see available pipes
    • Use pipelex show pipe pipe_code to inspect pipe details
    • Run with pipelex run pipe pipe_code, add the required inputs using --inputs

  4. Configuration Management

    • Use pipelex doctor to check that your configuration is healthy, and pipelex doctor --fix to fix what can be fixed
    • Use pipelex show config to verify current settings
    • Use pipelex show backends to check inference backend setup
    • Use pipelex show models backend_name to see available models