Reference

CLI reference

Commands, subcommands, common examples, and structured output support for the Linkar CLI.

Use this page when you know the command family you need. Use the guides when you want a worked path from a fresh project to a completed run.

Most commands accept -h or --help. Runtime and project-data commands generally support --format json and --format yaml for automation.

Common options

Help and versions

Use command-local help first; dynamic template subcommands expose the same help style.

linkar --help
linkar --version
linkar run --help
linkar run TEMPLATE --help

Structured output

Commands that report runtime or project state can emit machine-readable JSON or YAML.

linkar templates --format yaml
linkar project runs --format json
linkar inspect run fastqc_001 --format yaml

Execution

`linkar run TEMPLATE`

Execute a template. Render-mode templates reuse the visible project bundle unless --refresh is passed.

linkar run demultiplex --param run_name=HLMCNDRX7
linkar run methods --refresh

`linkar render TEMPLATE`

Stage a standalone editable bundle without executing it. The output directory must be empty or absent.

linkar render demultiplex --outdir ./demultiplex

`linkar collect RUN_REF`

Refresh declared outputs after manual execution and record the resulting run state.

linkar collect ./demultiplex
linkar collect fastqc_001 --state failed
linkar collect fastqc_001 --format yaml

`linkar clean [TARGET]`

Remove template-declared disposable runtime artifacts from a project or rendered template directory, using the latest configured pack cleanup rules when available. When TARGET is omitted, Linkar cleans the current directory.

linkar clean --dry-run
linkar clean
linkar clean ./demultiplex --yes

`linkar inspect run RUN_REF`

Inspect recorded metadata, params, outputs, warnings, and provenance.

linkar inspect run fastqc_001
linkar inspect run ./fastqc --format yaml

`linkar test TEMPLATE`

Run a template-local test.sh or test.py through Linkar.

linkar test fastqc --pack ./examples/packs/basic

Run and render share --pack, --binding, --project, --outdir, --param KEY=VALUE, --prompt/--no-prompt, and --format. run also supports --verbose and --refresh.

Projects

`linkar project init`

Create project.yaml in the target directory. Use --adopt to import existing runs while initializing.

linkar project init --name study
linkar project init --name study --adopt /path/to/run

`linkar project runs`

List runs recorded in project.yaml.

linkar project runs
linkar project runs --format yaml

`linkar project view`

Show project metadata and recorded runs.

linkar project view
linkar project view fastqc_001 --format yaml

`linkar project latest RUN_REF`

Return the newest matching recorded run.

linkar project latest fastqc
linkar project latest ./methods

`linkar project adopt-run RUN_REF`

Import existing Linkar run directories into the active project.

linkar project adopt-run /path/to/run

`linkar project remove-run RUN_REF`

Remove a run record, optionally deleting files.

linkar project remove-run fastqc_001
linkar project remove-run fastqc --delete-files

`linkar project prune`

Remove stale duplicate-path history.

linkar project prune --dry-run
linkar project prune --keep 2
linkar project prune --template methods --keep 1

`linkar project author ...`

Manage author metadata stored in project.yaml.

linkar project author show
linkar project author set --name "Project Owner"
linkar project author clear

Accepted run references include instance ids, unique template ids, visible project paths, run directory paths, and metadata JSON paths when unambiguous. Both project-central .linkar/meta/<instance_id>.json and legacy .linkar/meta.json paths are supported.

Packs

Project packs are saved in project.yaml. Global packs are saved in the user-level Linkar config. Use project packs when a project should carry its pack setup with it. Use global packs for personal defaults.

Project packs

Saved in project.yaml; use these when a project should carry its pack setup.

linkar pack add REF --id ID
linkar pack validate REF
linkar pack list
linkar pack use ID
linkar pack show
linkar pack status
linkar pack update ID
linkar pack update --all
linkar pack remove ID

Global packs

Saved in the user-level Linkar config; use these for personal defaults.

linkar config pack add REF --id ID
linkar config pack list
linkar config pack use ID
linkar config pack show
linkar config pack update ID
linkar config pack update --all
linkar config pack remove ID

Common examples:

linkar config pack add github:IZKF-Genomics/izkf_pack --id izkf_pack
linkar config pack use izkf_pack
linkar pack validate github:IZKF-Genomics/izkf_pack
linkar pack add github:IZKF-Genomics/izkf_pack --id izkf_pack --binding default
linkar pack status
linkar pack update izkf_pack

linkar pack validate REF checks every template contract and verifies that pack bindings refer to existing templates, parameters, outputs, and functions/NAME.py resolvers. It exits with status 1 when it finds an error and supports --format json or --format yaml for CI.

Discovery and automation

`linkar templates`

List templates visible from explicit packs and the active project configuration.

linkar templates
linkar templates --pack ./examples/packs/basic --format yaml

`linkar serve`

Expose the local project/runtime API over HTTP.

linkar serve --port 8000 --api-token local-dev:read,resolve,execute

`linkar mcp serve`

Start the stdio MCP server for agent clients.

linkar mcp serve

`linkar completion`

Print or install shell completion scripts for supported shells.

linkar completion zsh
linkar completion install zsh --yes
linkar completion install bash --rc-file ~/.bashrc
linkar completion install fish

`linkar config author ...`

Manage default author metadata for new projects.

linkar config author set --name "Your Name" --email "you@example.org"
linkar config author show
linkar config author clear

Use linkar templates before run or render when you want to verify which pack and template id will be visible from the current project context.