How to Use Lineage

How to Use Lineage

This page explains the current Lineage flow for package authors and receivers.

1. Install Lineage

curl -fsSL https://agenticlineage.vercel.app/install.sh | sh

The installer downloads the right prebuilt binary for macOS or Linux, verifies it against the published checksum, and installs it to ~/.lineage/bin.

Go developers can also build from source:

go install github.com/agentic-lineage/lineage/cmd/lineage@latest

2. Understand Package Shape

A Lineage package is a normal folder with a lineage.yaml manifest.

package/
├── lineage.yaml
├── skills/
├── workflows/
├── agents/
├── policies/
├── references/
└── adapters/

These folders are plain on purpose. You should be able to inspect what a package contains.

3. Initialize Local Lineage State

lineage init user

For a named workspace:

lineage init workspace <name>

4. Create A Package

lineage package init resume-workflow

Then add the package files, skills, workflows, references, policies, or adapters that belong to that environment.

5. Validate Before Sharing

Before a package leaves your machine, check it's safe and complete:

lineage package validate ./resume-workflow

This runs the same manifest, export-authority, path-safety, and secret-scan checks that export uses, and prints the package's content digest, without enabling or writing anything.

6. Share A Package As A File

lineage package export ./resume-workflow -o resume-workflow.tgz

export refuses to run if validation fails. The archive is deterministic — exporting the same content twice always produces the same bytes and the same digest — so a receiver can confirm they got exactly what you sent.

On the receiving machine:

lineage package import resume-workflow.tgz

import treats the archive as untrusted: it re-runs the full validation pass against the extracted content before keeping it, the same as if you'd run package validate yourself, and refuses to overwrite an already-imported package (use --as to import under a different name).

7. Publish Or Add From The Registry

If you want the package to be discoverable on the Lineage website, publish it to the registry. First authenticate with GitHub:

lineage login
lineage package publish ./resume-workflow

The first publish of a package name claims it for your verified GitHub login. To publish an update, bump version in lineage.yaml and publish again with the same identity.

Published packages appear at:

https://agenticlineage.vercel.app/packages

On the receiving end, the shortest path is:

lineage add resume-workflow

lineage add fetches the package, verifies its digest, shows what it contains, asks before enabling unless --yes is passed, and records it in the current project.

Use an exact version when reproducibility matters:

lineage add resume-workflow@0.2.0

You can still pull and enable separately if you want to inspect the imported copy first:

lineage package pull resume-workflow
lineage inspect resume-workflow
lineage enable resume-workflow

8. Enable A Local Package In A Project

From the project where you want to use the package:

lineage enable ./resume-workflow

This records the package in .lineage/config.yaml.

9. Inspect, List, And Diagnose

lineage list
lineage inspect resume-workflow
lineage doctor

list shows enabled packages in the current project. inspect shows package contents and declared capabilities without enabling anything. doctor checks project config, provider binary resolution, and shim setup.

10. Preview The Launch Plan

lineage run claude --dry-run
lineage run codex --dry-run

The dry run shows which provider, project config, and packages Lineage would use, and never writes anything.

11. Run Through A Provider

lineage run claude

The first time this would actually stage files for a provider — skills into its own directory, a generated section into its context file — it shows what it's about to create or change and asks for confirmation. Answer y/yes, or pass --yes/-y to skip the prompt in scripts. Re-running with an unchanged package set doesn't ask again.

Lineage can also install shims so normal provider commands enter Lineage first:

lineage install-shims

Then put the shim directory before existing provider binaries in PATH.

12. Run A Declared Workflow

If a package declares an ordered workflow, run only that workflow's steps:

lineage workflow run resume-review claude --dry-run
lineage workflow run resume-review claude

Workflow runs use the same dry-run and permission-gated materialization model as plain lineage run.

Safety Rule

Do not package secrets, credentials, provider login state, private prompts, .env values, or machine-local cache files.

If a workflow needs receiver-specific values, package a template or setup prompt instead.

Declared filesystem and network capabilities are visible to receivers, but they are not a sandbox in this build.