Skip to content

Run a Method by Address

Every command that takes an installed method name — pipelex run method, pipelex validate method, the pipelex build method commands, and their agent-CLI twins — also accepts a method reference: a globally resolvable address pointing at a package in a public GitHub repository. Pipelex fetches the repository, locates the package inside it, and runs it, with no install step.

# Run a method from the public library at a pinned tag
pipelex run method github.com/Pipelex/methods/documents@v0.1.0 --inputs inputs.json

# Same method, default branch at HEAD (no tag)
pipelex run method github.com/Pipelex/methods/documents --pipe extract_document_text

# Validate a method by address
pipelex validate method github.com/Pipelex/methods/documents --pipe extract_document_text

The reference grammar

A method reference is <address>[@<tag>]:

  • The address is github.com/<owner>/<repo>[/<selector>] (GitHub only for now). The first two path segments name the repository — the clone URL is derived as https://github.com/<owner>/<repo>.git — and anything after them selects a package within the repository.
  • A bare address (no @<tag>) means the repository's default branch at HEAD.
  • @<tag> pins the repository at that git tag. The recommended form is vX.Y.Z (e.g. @v0.2.0). The name must be a tag — a branch name after @ is refused, so only tags pin a revision.

Full browser URLs keep working: https://github.com/owner/repo (with or without .git) is normalized into the address form, and a /tree/<branch>/... deep link is accepted with the branch segment discarded — only tags pin a revision.

Every fetch prints its provenance — the resolved package address, the tag when one was named, and the commit SHA of what was actually cloned. Tags can move; the SHA is what makes a run reproducible and explainable.

How the package is located: manifest identity

The package inside the clone is located by manifest identity, not directory path. Pipelex scans the clone for METHODS.toml files and selects the one whose identity matches the requested address:

  • A repo-root package matches when its manifest address equals the requested address.
  • A package in a library repo matches when its manifest address + "/" + name equals the requested address. For example, in Pipelex/methods the documents package's manifest carries address = "github.com/Pipelex/methods" and name = "documents", so its full address is github.com/Pipelex/methods/documents — wherever it sits in the repository tree.

Address comparison is case-insensitive, matching GitHub's own behavior for owner and repository names.

No match, or more than one, is a loud error listing the packages the clone does contain — so requesting a library repo's bare address tells you which packages it offers.

The entry pipe

The pipe to run defaults to the manifest's main_pipe; --pipe <code> overrides it. A method with no main_pipe requires --pipe.

Where outputs land

The fetched clone is temporary: it lives in a system temp directory and is deleted when the CLI process exits. Default outputs therefore anchor in your current working directory — pipelex run method <ref> writes into ./results/, and the pipelex build method commands write their generated files there too, so nothing you produced disappears with the clone. An explicit --output-dir / --output is honored verbatim. For an installed method or a local path, defaults stay inside the method's own directory, as before.

Running by address on the hosted API

With --hosted (or [run] execution = "hosted"), pipelex run method <ref> fetches nothing: the address goes to the hosted Pipelex API as a method reference, and the hosted runner locates and fetches the package itself, under the same grammar and the same manifest-identity rule. The entry pipe is still the manifest's main_pipe unless --pipe names another, outputs still land in ./results/ under your working directory, and a relative --inputs path resolves against the working directory, since there is no local clone to anchor it to. -L is refused, because the hosted API loads no local library alongside an address. See Running on the Hosted API.

pipelex run method github.com/Pipelex/methods/text_stats@v0.1.7 --hosted --inputs '{"text": "Hello world."}'

Python in fetched methods: the hosted rule

What decides whether Python in a method is acceptable is where it would execute:

  • .mthds content is data — always fine.
  • PipeFunc .py is supported: on hosted deployments it executes in a network-blocked sandbox, never in the runner's process. This holds for a package the hosted runner fetches by its address; a local bundle sent with --hosted carries only its .mthds files, so its PipeFuncs stay behind (see Running on the Hosted API).
  • Python structure classes (StructuredContent subclasses) would have to be imported into the runner's own process to back a concept, so hosted execution accepts MTHDS concepts and sandboxed PipeFuncs, not in-process Python. A fetched method declaring structure classes runs locally, but the CLI prints a hosted-parity warning with the route: declare the types as MTHDS concepts with inline structures, and have a PipeFunc import the classes the sandbox generates from them (from structures import <domain>__<Concept>). The module pipelex build structures writes is accepted as long as it is left as generated.

Bounds

Fetched packages are bounded: the clone has a fixed timeout, and the selected package is capped in file count and total bytes (tunable via the PIPELEX_MAX_FETCHED_PACKAGE_FILES and PIPELEX_MAX_FETCHED_PACKAGE_TOTAL_KIB environment variables). The manifest scan that locates the package is bounded too: at most PIPELEX_MAX_SCANNED_MANIFESTS manifests are considered per repository, and each METHODS.toml is read only if it is a regular file. A METHODS.toml that is a symlink, or is not a regular file, is skipped and reported without ever being opened, so a repository cannot make the scan read a file outside the clone. The read itself stops at PIPELEX_MAX_MANIFEST_FILE_KIB, whatever size the file reports, and a manifest over that ceiling, or not valid UTF-8, is skipped and reported too. Content exceeding the caps is rejected with a clear error. Symlinks are refused outright: a fetched package containing one (file or directory) is rejected, because a link's target would bypass the content scans.

Referencing a Method by Address from Your Own Method

The same addresses work inside a bundle: a pipe step can reference another method's pipe as github.com/...->domain.pipe_code, and a reference that misses the installed methods is fetched and installed automatically (fetch-on-miss). See Packages → Include by Address.