Skip to content

Build Output

Generate output representation for a pipe, showing the expected output structure based on the pipe's output concept type. Supports multiple output formats including JSON Schema for TypeScript/Zod integration.

Usage

By pipe code

pipelex build output 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 file (defaults to results/)
  • --format, -f - Output format (default: json):
    • json - JSON object with example placeholder data
    • python - Python class instantiation code
    • schema - JSON Schema definition, ideal for generating TypeScript interfaces or Zod schemas

From a bundle

pipelex build output bundle <PATH> [OPTIONS]

A folder is read as its method tree, as pipelex run bundle reads it. With no --pipe, the representation 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 output: .... Either way the file is written in the folder unless --output says otherwise.

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 file (defaults to the method's folder, or to the bundle file's directory)
  • --format, -f - Output format (default: json): json, python, or schema

From an installed method

pipelex build output 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 file
  • --format, -f - Output format (default: json): json, python, or schema

Examples

Generate output for a pipe by code:

pipelex build output pipe my_domain.my_pipe

Generate output from a bundle (uses main_pipe):

pipelex build output bundle my_bundle.mthds

Generate JSON Schema from a bundle for TypeScript/Zod integration:

pipelex build output bundle my_bundle.mthds --format schema

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

pipelex build output bundle pipeline_01/

Specify which pipe to use from a bundle:

pipelex build output bundle my_bundle.mthds --pipe my_pipe

Generate output for a pipe using a library directory:

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

Custom output path:

pipelex build output bundle my_bundle.mthds --output expected_output.json

Output Formats

JSON Format (default)

The JSON format generates example placeholder data showing the output structure:

{
  "concept": "my_domain.MyOutputConcept",
  "content": {
    "title": "title_value",
    "key_points": "key_points_value"
  }
}

For native concepts like Text, Image, or Document:

{
  "concept": "native.Text",
  "content": {
    "text": "text_value"
  }
}

When a pipe's output has multiplicity (returns multiple items), the content is a list:

{
  "concept": "my_domain.Item",
  "content": [
    {
      "name": "name_value",
      "description": "description_value"
    }
  ]
}

Python Format

The Python format generates class instantiation code:

{"concept": "my_domain.MyOutputConcept", "content": 'MyOutputConcept(title="title_value", key_points="key_points_value")'}

Schema Format

The schema format generates JSON Schema definitions, ideal for generating TypeScript interfaces or Zod schemas. The schema's top-level title is the concept ref, and its top-level description is the concept's authored description:

{
  "concept": "my_domain.MyOutputConcept",
  "content": {
    "type": "object",
    "properties": {
      "title": { "type": "string", "title": "Title" },
      "key_points": { "type": "string", "title": "Key Points" }
    },
    "required": ["title", "key_points"],
    "title": "my_domain.MyOutputConcept",
    "description": "The concept's description, as authored in the bundle"
  }
}

Array outputs are represented as JSON Schema arrays, with the concept identity kept on items. A fixed count (e.g., MyType[5]) additionally emits minItems/maxItems bounds; a variable-length list (MyType[]) carries no bounds:

{
  "concept": "my_domain.Item",
  "content": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "name": { "type": "string", "title": "Name" },
        "description": { "type": "string", "title": "Description" }
      },
      "required": ["name", "description"],
      "title": "my_domain.Item",
      "description": "An item of the collection"
    },
    "minItems": 5,
    "maxItems": 5
  }
}

native.Anything Output

When a pipe's output is native.Anything (e.g., a PipeCondition with mapped pipes that have different output types), the command shows all possible outputs from the mapped pipes.

For JSON format:

{
  "output_option_1": {
    "concept": "my_domain.Result1",
    "content": { "field1": "field1_value" }
  },
  "output_option_2": {
    "concept": "my_domain.Result2",
    "content": { "field2": "field2_value" }
  }
}

For schema format:

{
  "schema_option_1": {
    "concept": "my_domain.Result1",
    "content": {
      "type": "object",
      "properties": { "field1": { "type": "string" } },
      "required": ["field1"]
    }
  },
  "schema_option_2": {
    "concept": "my_domain.Result2",
    "content": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": { "field2": { "type": "string" } },
        "required": ["field2"]
      }
    }
  }
}

This helps you understand all possible output structures that the pipe could return depending on execution path.

Use Cases

  • Understanding pipe outputs - Quickly see what structure a pipe returns
  • API integration - Know the exact structure to expect when calling pipes programmatically
  • TypeScript/Zod integration - Use --format schema to generate JSON Schema, then convert to TypeScript interfaces or Zod schemas for type-safe frontend integration
  • Type definitions - Use as reference for defining types in your application code
  • Testing - Create expected output templates for validation