Skip to content

Build Inputs

Generate an example inputs template for a pipe, showing the expected input structure based on the pipe's input types. The template is emitted as JSON by default, or as TOML with --format toml.

By default the template is the light shape — the values themselves, matching the pipe's declared signature (a bare string for a Text-refining input, a bare number for a Number-refining one, an object for a structured concept). This is exactly what pipelex run accepts, so a template you generate and fill in runs as-is. Pass --explicit to emit the ceremonial {concept, content} envelope form instead. See Providing Inputs for the full model.

Usage

By pipe code

pipelex build inputs pipe <PIPE_CODE> [OPTIONS]

Arguments:

  • PIPE_CODE - The pipe code (e.g. my_domain.my_pipe)

Options:

  • --library-dir, -L - Directory to search for pipe definitions. Can be specified multiple times.
  • --output, -o - Path to save the generated inputs file (defaults to results/, filename inputs.json or inputs.toml depending on --format)
  • --format - Template format: json (default) or toml
  • --explicit - Emit the ceremonial {concept, content} envelope form instead of the light values

From a bundle

pipelex build inputs bundle <PATH> [OPTIONS]

A folder is read as its method tree, as pipelex run bundle reads it. With no --pipe, the template is for the pipe a run of the folder starts at: the manifest's main_pipe, or, with no manifest, the one main_pipe its bundles declare. A folder whose bundles declare none, or several, is refused with the message run bundle gives, naming each bundle by its path in the tree. The bundle defining that pipe loads with the rest of the method's folder and the -L directories, as a run loads it, so a concept or a pipe it takes from a sibling bundle resolves. With --pipe, the folder loads as the method's library and the pipe named is looked up there, as a run naming its pipe does. A refusal names the command, as in Failed to build inputs: .... Either way the file is written in the folder unless --output says otherwise, so pipelex run bundle on the same folder finds it.

Arguments:

  • PATH - Path to a .mthds bundle file or a method's folder

Options:

  • --pipe - Pipe code to use (can be omitted if the bundle, or the method's folder, declares a main_pipe)
  • --library-dir, -L - Directory to search for pipe definitions. Can be specified multiple times.
  • --output, -o - Path to save the generated inputs file (defaults to the method's folder, or to the bundle file's directory, filename inputs.json or inputs.toml depending on --format)
  • --format - Template format: json (default) or toml
  • --explicit - Emit the ceremonial {concept, content} envelope form instead of the light values

From an installed method

pipelex build inputs method <NAME> [OPTIONS]

Arguments:

  • NAME - Name of the installed method, a method address (github.com/owner/repo[/name][@tag]), or a GitHub URL — see Run a Method by Address

Options:

  • --pipe - Pipe code (overrides method's main_pipe)
  • --library-dir, -L - Directory to search for pipe definitions. Can be specified multiple times.
  • --output, -o - Path to save the generated inputs file (filename inputs.json or inputs.toml depending on --format)
  • --format - Template format: json (default) or toml
  • --explicit - Emit the ceremonial {concept, content} envelope form instead of the light values

Examples

Generate inputs for a pipe by code:

pipelex build inputs pipe my_domain.my_pipe

Generate inputs from a bundle (uses main_pipe):

pipelex build inputs bundle my_bundle.mthds

Generate inputs for the main pipe of a method's folder:

pipelex build inputs bundle pipeline_01/

Specify which pipe to use from a bundle:

pipelex build inputs bundle my_bundle.mthds --pipe my_pipe

Generate inputs for a pipe using a library directory:

pipelex build inputs pipe my_domain.my_pipe -L ./my_library/

Custom output path:

pipelex build inputs bundle my_bundle.mthds --output custom_inputs.json

Generate a TOML template instead of JSON:

pipelex build inputs bundle my_bundle.mthds --format toml

When --format toml is selected and no explicit --output is given, the default filename becomes inputs.toml (instead of inputs.json).

Generate the explicit envelope form instead of the light values:

pipelex build inputs bundle my_bundle.mthds --explicit

Output Format

The generated file contains all inputs required by the pipe, with example values based on each input's concept type. Both formats carry the same structure — pipelex run accepts either.

Light form (default)

The default template is the light shape: each value is what the pipe's signature expects, with no {concept, content} envelope. For a pipe declaring a Text-refining question, a Number-refining priority, a structured invoice, and a Text-refining list tags = "Tag[]":

JSON (--format json, default):

{
  "question": "text_value",
  "priority": 1,
  "invoice": {
    "invoice_number": "invoice_number_value",
    "amount": 0.0
  },
  "tags": ["text_value"]
}

TOML (--format toml): the light TOML template uses inline tables so top-level scalars and structured values coexist, and carries the declared concept for each key as a comment (a declared-multiple input is tagged []):

# concept: my_domain.Question
question = "text_value"
# concept: my_domain.Priority
priority = 1
# concept: my_domain.Invoice
invoice = {invoice_number = "invoice_number_value", amount = 0.0}
# concept: my_domain.Tag[]
tags = ["text_value"]

Explicit envelope form (--explicit)

Pass --explicit to reproduce the ceremonial {concept, content} envelope for every input — useful when you want the concept written out inline (JSON has no comments), or when authoring an input meant for the explicit escape hatch:

{
  "question": {
    "concept": "my_domain.Question",
    "content": {"text": "text_value"}
  },
  "priority": {
    "concept": "my_domain.Priority",
    "content": {"number": 1}
  },
  "invoice": {
    "concept": "my_domain.Invoice",
    "content": {"invoice_number": "invoice_number_value", "amount": 0.0}
  },
  "tags": {
    "concept": "my_domain.Tag",
    "content": [{"text": "text_value"}]
  }
}

In TOML, --explicit renders the all-tables layout; a multiple input keeps a single [key] envelope whose content is an array-of-tables ([[key.content]]):

[question]
concept = "my_domain.Question"

[question.content]
text = "text_value"

# ... priority and invoice tables omitted ...

[tags]
concept = "my_domain.Tag"

[[tags.content]]
text = "text_value"

Multiplicity

When an input is declared multiple (Tag[]), the light form wraps the example value in a list (["text_value"]); the explicit form keeps a single {concept, content} envelope whose content is the list (not an array of separate envelopes). Either way, pipelex run accepts the filled-in template.

Use Cases

  • Understanding pipe requirements - Quickly see what inputs a pipe expects
  • Creating input templates - Generate a starting point for your input JSON files
  • API integration - Know the exact structure to send when calling pipes programmatically