Back to docs

Concept

Project lifecycle

A practical end-to-end view of how projects move from initialization to cleanup.

This page is the shortest way to understand how a typical Linkar project evolves over time.

The common flow

For most project work, the lifecycle is:

  1. project init
  2. attach or select packs
  3. render when you want an editable bundle
  4. run when you want Linkar to execute the template
  5. collect after manual execution of a rendered bundle
  6. clean before export or archive when templates declare disposable runtime artifacts
  7. inspect run to review metadata and provenance
  8. project latest when you want the newest active recorded run
  9. project prune when stale duplicate-path history accumulates

The planned default for project work is an active-workspace model:

  • one project plus one template id has one active visible workspace
  • rerendering refreshes that workspace after confirmation
  • extra instances and historical entries are opt-in
  • temporary render directories are not silently registered as the canonical project entry

Step 1: initialize a project

Create a new project directory with project.yaml:

linkar project init --name study
cd study

At this point the project ledger exists, but it contains no recorded runs yet. New projects also record the project schema version and the Linkar version that created the ledger.

Step 2: attach packs

Projects can use:

  • explicit --pack references on a single command
  • project-local packs stored in project.yaml
  • global packs from user config

Typical project-local setup:

linkar pack add /path/to/pack --id my_pack
linkar pack list

Step 3: render an editable bundle

Use render when you want to stage files without executing them:

linkar render demultiplex --outdir ./demultiplex

This is especially useful when:

  • the generated run.sh should be reviewed or edited
  • downstream execution happens on another machine
  • a user wants to inspect the exact command before running it

Rendered bundles are recorded in project.yaml with state: rendered.

In the planned active-workspace model, rendering the same template id again will update the existing visible workspace and replace that template’s active project.yaml entry by default. The CLI should ask before overwriting a non-empty workspace. Use --new-instance when you intentionally want a second project entry for the same template.

Step 4: run a template

Use run when Linkar should execute the template:

linkar run demultiplex

For ordinary run-mode templates, Linkar typically keeps:

  • a visible project-facing path such as ./demultiplex
  • immutable run history under .linkar/runs/<instance_id>

For templates declared with run.mode: render, the behavior is different:

  • run executes directly in the visible project path
  • the visible bundle is reused by default
  • --refresh rerenders the bundle before execution

Example:

linkar run methods --outdir ./methods --refresh

Step 5: collect outputs after manual execution

If a user runs a rendered run.sh manually, Linkar can still refresh outputs and metadata:

linkar collect ./demultiplex

collect updates declared outputs in:

  • the registered metadata JSON (.linkar/meta/<instance_id>.json in a project)
  • project.yaml when the run belongs to the active project

It records the manually executed run as completed by default. If the manual command failed, use linkar collect RUN_REF --state failed; use --state rendered when collecting without asserting that execution finished.

The CLI now tells you whether the active project ledger was updated or left unchanged, so it is easier to distinguish:

  • collected outputs for a project-registered run
  • collected outputs for an ad hoc run outside any active project

Accepted run references include:

  • instance ids such as fastqc_001
  • unique template ids when unambiguous in the project
  • run directory paths
  • project-central or legacy metadata JSON paths

Step 6: clean runtime artifacts

Use clean when you want to remove template-declared disposable runtime artifacts before export, archive, or handoff:

linkar clean . --dry-run
linkar clean .

From a project root, linkar clean . resolves the recorded template directories in project.yaml and applies each template’s cleanup rules. From a rendered template directory, it cleans only that one directory.

If a current configured pack contains the same template id, cleanup uses the latest cleanup rules from that pack. This lets pack maintainers add newly known runtime artifacts, such as workflow cache directories, and clean older rendered workspaces without rerendering them.

By default, the CLI prints the folders and files that would be removed and asks for confirmation in the terminal. Use --yes only for non-interactive scripts.

Cleanup rules come from the template contract, so Linkar does not hard-code domain-specific patterns such as Nextflow work/ or Pixi .pixi/.

Step 7: inspect provenance

Use inspect run to read recorded metadata:

linkar inspect run fastqc_001
linkar inspect run fastqc
linkar inspect run ./fastqc

This is the primary way to answer:

  • what params were resolved
  • what command was executed
  • what outputs were collected
  • what warnings were recorded

Step 8: ask for the newest active recorded run

Sometimes you do not want the whole history. You only want the newest recorded run for a template or visible path.

Use:

linkar project latest methods
linkar project latest ./methods

This is useful when:

  • a template has been rerun several times
  • you want the current visible run quickly
  • you want a stable precursor before inspect run or export logic

Step 9: prune stale history

Over time, rerendering or replacing visible bundles can leave older duplicate-path entries in project.yaml.

This is current-release cleanup behavior. After the active-workspace model is implemented, prune will mostly be a migration and explicit-history tool rather than something needed during ordinary rerendering.

Use:

linkar project prune --dry-run
linkar project prune

By default, project prune:

  • keeps the newest run for each visible project path
  • removes stale duplicate-path entries from project.yaml
  • deletes orphaned historical run directories for the pruned entries

If you want to keep shallow recent history instead of only one survivor, use:

linkar project prune --keep 2

Use --keep-files if you only want to clean metadata and keep directories on disk.

Practical rule of thumb

Use:

  • render when you want an editable workspace
  • run when Linkar should execute now
  • collect when execution happened outside Linkar
  • clean when disposable template artifacts would make export or archive too large
  • inspect run when you need provenance
  • project prune when history has become cluttered

When you script these steps, prefer --format json or --format yaml on execution commands. The default plain stdout stays intentionally minimal and prints the primary path only.

  • Project runs and metadata explains what is recorded in project.yaml and .linkar/
  • Template runtime contract explains how templates declare run behavior
  • Interfaces and automation explains how the CLI, API, and MCP share the same semantics