Back to tutorials

Tutorial

Getting started with a local project

Create a project, add a pack, run your first template, and inspect the result.

This tutorial is the normal human starting path.

You already have a reusable pack. You want to attach it to a local project, run one template, and inspect the result without learning the whole internals first.

Install Linkar as a CLI tool first.

Recommended:

pipx install git+https://github.com/chaochungkuo/linkar.git

Alternative for uv users:

uv tool install git+https://github.com/chaochungkuo/linkar.git

These are user-facing install paths. Template-local Pixi environments and editable installs belong to template authoring or Linkar repo development, not to normal Linkar usage.

First run

Start with the shortest useful flow:

linkar config author set --name "Your Name" --email "you@example.org" --organization "IZKF"
linkar project init --name study
cd study
linkar pack add ../examples/packs/basic --id basic
linkar run simple_echo --name Linkar
linkar inspect run simple_echo_001

This gives you:

  • a normal project directory
  • project.yaml
  • reused author metadata from your global Linkar config
  • a stable project-root directory such as ./simple_echo
  • immutable run history under .linkar/runs/
  • .linkar/runs/<instance_id>/.linkar/meta.json for provenance
  • the option to render a standalone artifact with linkar render ...

If the project-level author metadata should differ from your global defaults, update it directly in the existing project:

linkar project author show
linkar project author set --name "Project Owner" --email "owner@example.org"

What happens after linkar run

In project mode, Linkar now separates:

  • the stable project-facing alias, such as ./simple_echo
  • the immutable recorded run under .linkar/runs/simple_echo_001

That means the project root stays readable while the real history remains preserved.

Typical next commands

linkar project runs
linkar inspect run simple_echo_001
linkar templates

Use linkar project runs to review what happened locally, and linkar inspect run to read the metadata and outputs for one recorded run.

If you started with an ad hoc run before creating a project, you can adopt it when initializing the project:

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

If you want a standalone runnable artifact instead of an executed run:

linkar render simple_echo --pack ./examples/packs/basic --param name=Linkar --outdir ./simple_echo
cd simple_echo
bash run.sh
linkar collect .

This is the Linkar user path.

Template authoring is separate. Template repos can use test.sh, test.py, Pixi, pytest, or other local tooling, but that is template-author workflow rather than the main Linkar runtime path.