Init CLI Flows

pipelex init sets up the .pipelex/ configuration directory. It handles four independent concerns — config files, inference backends, routing profiles, and telemetry — through a focus-based dispatch system. Each concern owns its own file-copying and customization logic, so they can be run together or individually without interference.

Why This Design

The .pipelex/ directory contains two categories of files with different lifecycles:

1. Config files (pipelex.toml, plxt.toml, mthds_schema.json) — static templates, copied once, rarely touched by the user.
2. Inference files (inference/backends.toml, inference/routing_profiles.toml, inference/backends/*.toml, inference/deck/*.toml) — interactive setup, customized per-project based on which AI backends the user selects.

These two categories are managed by separate steps. init_config() copies only config files (skipping the inference/ directory entirely). The inference step handles its own template copying and then runs interactive backend selection and routing customization. Each file is owned by exactly one step — init_config() explicitly skips the inference/ directory via INIT_SKIP_DIRS, and skips telemetry.toml and pipelex_service.toml via INIT_SKIP_FILES. This separation ensures that re-running pipelex init config never overwrites a user's carefully tuned inference setup.

Interfaces

CLI Commands

All commands except agreement and credentials perform a full reset (overwrite existing files). Config updates are not yet supported.

Inputs

• focus (InitFocus enum): Determines which steps run. Derived from the CLI subcommand.
• skip_confirmation (bool): When True, skips the interactive confirmation prompt. Used when called from pipelex doctor --fix.
• local (bool): When True, targets the project-level .pipelex/ directory instead of the global ~/.pipelex/. Maps to the --local CLI flag.

Outputs / Side Effects

Architecture

Overall Flow

flowchart TD
    START([pipelex init]) --> FOCUS{focus?}

    FOCUS -- agreement --> AGREE[_init_agreement]
    AGREE --> DONE([Done])

    FOCUS -- credentials --> CREDS_DIRECT["prompt_credentials<br/>Prompt for missing API keys"]
    CREDS_DIRECT --> DONE

    FOCUS -- "all / config / inference / routing / telemetry" --> NEEDS[determine_needs]
    NEEDS --> CONFIRM{User confirms?}
    CONFIRM -- No --> CANCEL([Cancelled])
    CONFIRM -- Yes --> EXEC[execute_initialization]

    EXEC --> S1{needs_config?}
    S1 -- Yes --> INITCFG["init_config()<br/>Copies non-inference files"]
    INITCFG --> DETECT{backends.toml<br/>existed before?}
    DETECT -- "No (first time)" --> FORCE_INF[Force needs_inference = True]
    DETECT -- Yes --> CHK_INF{check_inference<br/>in focus?}
    CHK_INF -- Yes --> FORCE_INF
    CHK_INF -- No --> GW_CHK[Check gateway terms]

    S1 -- No --> S2

    FORCE_INF --> S2
    GW_CHK --> S2

    S2{needs_inference?}
    S2 -- Yes --> COPY_INF["Copy inference templates<br/>(backends, deck, routing)"]
    COPY_INF --> CUST_BE[customize_backends_config<br/>Interactive backend selection]
    CUST_BE --> CHK_RT{check_routing?}
    CHK_RT -- "No (auto-route)" --> CUST_RT[customize_routing_profile<br/>Auto-routing based on selection]
    CUST_RT --> S25
    CHK_RT -- "Yes (focus=routing)" --> S25

    S2 -- No --> S25

    S25{check_credentials?}
    S25 -- Yes --> CREDS["prompt_credentials<br/>Prompt for missing API keys"]
    S25 -- No --> S3
    CREDS --> S3

    S3{needs_routing?}
    S3 -- Yes --> ROUTE[customize_routing_profile<br/>Standalone routing setup]
    S3 -- No --> S4

    ROUTE --> S4

    S4{needs_telemetry?}
    S4 -- Yes --> TELEM[setup_telemetry<br/>Copy telemetry template]
    S4 -- No --> DONE2([Done])

    TELEM --> DONE2

Implementation

Determine Needs

determine_needs() evaluates the current state of .pipelex/ to decide which steps are required:

nb_missing_config_files = init_config(reset=False, dry_run=True) if check_config else 0
needs_config = check_config and (nb_missing_config_files > 0 or reset)
needs_inference = check_inference and (not path_exists(backends_toml_path) or reset)
needs_routing = check_routing and (not path_exists(routing_profiles_toml_path) or reset)
needs_telemetry = check_telemetry and (not path_exists(telemetry_config_path) or reset)

The check_* flags are derived from the focus parameter:

Step 1: Config Step — init_config()

Copies the config template tree from kit/configs/ to .pipelex/, with two skip mechanisms:

INIT_SKIP_FILES: frozenset[str] = GIT_IGNORED_CONFIG_FILES | {TELEMETRY_CONFIG_FILE_NAME, ".DS_Store"}
INIT_SKIP_DIRS: frozenset[str] = frozenset({"inference"})

The recursive copy_directory_structure function checks both sets before processing each entry:

if item in INIT_SKIP_FILES:
    continue
if os.path.isdir(src_item):
    if item in INIT_SKIP_DIRS:
        continue
    # recurse...

First-Time Inference Detection

After init_config() runs, execute_initialization decides whether inference setup is needed — even if inference was not in the original focus:

backends_existed_before = path_exists(backends_toml_path)
init_config(reset=reset)
backends_exists_now = path_exists(backends_toml_path)

if not backends_existed_before or (check_inference and backends_exists_now):
    needs_inference = True

This handles two scenarios:

When inference is not forced and backends already exist, gateway terms are still checked:

if not needs_inference and backends_existed_before:
    _check_gateway_terms_if_needed(console, backends_toml_path)

Step 2: Inference Step

When needs_inference is True and reset is True, the inference step copies its own template files independently:

1. backends.toml — main backend registry
2. backends/*.toml — per-backend configuration files
3. deck/*.toml — model deck configurations
4. routing_profiles.toml — routing profile definitions

Then runs interactive customization:

1. customize_backends_config() — prompts user to select backends, handles gateway terms, and suggests IDE extension installation via suggest_extension_install_if_needed()
2. customize_routing_profile() — auto-configures routing based on selected backends (only when check_routing is False, i.e. when routing is not the specific focus)

When focus=routing, the inference step skips routing entirely because Step 3 handles it as a standalone operation.

Step 2.5: Credentials Step

When check_credentials is True (for focus in all, config, inference), prompt_credentials() checks which backends are enabled and prompts the user for any missing API keys. Credentials are stored in ~/.pipelex/.env with mode 0600.

Step 3: Routing Step

If needs_routing is True (only for focus=routing), runs customize_routing_profile() as a standalone step.

Step 4: Telemetry Step

Copies the telemetry.toml template and prints instructions. No interactive prompts.

Scenario Matrix

File Reference

Template Directory (kit/configs/)

Skip Lists

Source Modules

Config Directory Resolution

The ConfigLoader (singleton: config_manager) resolves where configuration files live. Understanding this logic is essential because bugs in directory resolution cause files to be written or read from the wrong location.

Source: pipelex/system/configuration/config_loader.py

Three Directory Properties

Project Root Detection

find_project_root() walks up from cwd looking for marker files:

• .git, pyproject.toml, setup.py, setup.cfg, package.json, .hg

The home directory (~) is explicitly excluded — even if it contains a package.json, it is never treated as a project root.

File Resolution Order

resolve_config_file(relative_path, config_dir) uses layered resolution:

flowchart TD
    START([resolve_config_file]) --> EXPLICIT{config_dir<br/>provided?}
    EXPLICIT -- Yes --> USE_EXPLICIT["Return config_dir / relative_path"]
    EXPLICIT -- No --> PROJECT{project_config_dir<br/>exists?}
    PROJECT -- Yes --> FILE_EXISTS{file exists in<br/>project dir?}
    FILE_EXISTS -- Yes --> USE_PROJECT["Return project_dir / relative_path"]
    FILE_EXISTS -- No --> USE_GLOBAL["Return global_dir / relative_path"]
    PROJECT -- No --> USE_GLOBAL

This means a project-level file wins over the global one, but only if it actually exists on disk.

Global Config Bootstrap

ensure_global_config_exists() creates ~/.pipelex/ with kit template files on first use (called automatically during load_config()). It skips all GIT_IGNORED_CONFIG_FILES (files like pipelex_service.toml) and .DS_Store — these are never part of the bootstrap copy.

Config Loading Chain

load_config() merges configuration in this order (later values override earlier ones):

1. Package defaults (pipelex/pipelex.toml)
2. Global config (~/.pipelex/pipelex.toml)
3. Project config ({project_root}/.pipelex/pipelex.toml, if different from global)
4. Override files from the effective config dir (local, environment, run mode, override)

Gateway Terms: Always Global

pipelex_service.toml is always written to and read from ~/.pipelex/, never from a project directory. This is an intentional invariant.

Why: Gateway terms are a user-level agreement, not a per-project setting. Accepting terms once should apply everywhere.

Write Locations

All writers explicitly target config_manager.global_config_dir:

Read Locations

Rules

• mkdir before writing: All write paths ensure the config directory exists before writing. Some callers call global_config_dir.mkdir(parents=True, exist_ok=True) explicitly, and update_service_terms_acceptance() itself ensures the directory exists, so every path is protected.
• Git-ignored: pipelex_service.toml is in GIT_IGNORED_CONFIG_FILES, so it is never copied by init_config() and never synced to a project directory.

Source: pipelex/system/pipelex_service/pipelex_service_agreement.py, pipelex/system/pipelex_service/pipelex_service_config.py

Agent CLI Init

pipelex-agent init is the non-interactive counterpart to pipelex init. It runs the same steps but takes all inputs from a JSON config argument instead of interactive prompts.

Source: pipelex/cli/agent_cli/commands/init_cmd.py

Target Directory Resolution

_resolve_target_dir(global_) determines where files are written:

If no project root is found and --global is not set, the command fails with an error.

Config Input

--config / -c accepts a JSON string (inline or file path) with these optional fields:

Flow

flowchart TD
    START([pipelex-agent init]) --> PARSE["Parse --config JSON"]
    PARSE --> RESOLVE["Resolve target dir<br/>(project or --global)"]
    RESOLVE --> STEP1["Step 1: init_config()<br/>Copy config templates (skips inference/)"]
    STEP1 --> STEP15["Step 1.5: Copy inference templates<br/>(backends.toml, backends/*, deck/*, routing_profiles.toml)"]
    STEP15 --> STEP2["Step 2: Configure backends<br/>Enable requested backends in backends.toml"]
    STEP2 --> GW{pipelex_gateway<br/>in backends?}
    GW -- Yes --> TERMS["Write gateway terms to ~/.pipelex/<br/>(always global)"]
    GW -- No --> STEP3
    TERMS --> STEP3["Step 3: Configure routing<br/>Auto-derive routing profile"]
    STEP3 --> STEP4["Step 4: Configure telemetry<br/>Copy template + apply mode"]
    STEP4 --> OUTPUT["Output structured JSON result"]

Key Differences from Interactive Init

Doctor Fix: Config Dir Handling

pipelex doctor and pipelex doctor --fix use the config directory resolution to find and fix configuration issues wherever they live.

Source: pipelex/cli/commands/doctor_cmd.py

How Each Check Resolves Files

Fix Targeting

When --fix replaces an outdated backend file, it derives the config directory from the resolved file path:

# File lives at {config_dir}/inference/backends/{name}.toml
# Walk up 3 levels to get the config_dir
resolved_config_dir = Path(backend_file_report.file_path).parent.parent.parent
replace_backend_file(backend_name, config_dir=resolved_config_dir)

This ensures the fix targets the same directory where the issue was found — if the broken file was in the project .pipelex/, the replacement goes there too, not to ~/.pipelex/.

Next Steps

• Configuration Internals
• Architecture Overview