> ## Documentation Index
> Fetch the complete documentation index at: https://docs.substrate.42.pe/llms.txt
> Use this file to discover all available pages before exploring further.

# Installing Substrate: Clone, Build, Link, and Verify

> Install the Substrate binary from a local clone, link it globally, and install the agent skill. Node.js 20+ required. No accounts or global config needed.

Substrate is a single binary that you install once and use across projects. There is nothing to sign up for and nothing to configure globally — each project keeps its own state in a local `.substrate/` directory. This guide walks you through building from source, linking the binary to your PATH, and installing the agent skill.

## Requirements

* **Node.js 20 or later**
* **macOS or Linux** (primary support; Windows is best-effort — WSL is recommended on Windows)
* A package manager: `pnpm` is used for the build steps below

<Note>
  Substrate v0.7.0 is a pre-release and is not yet published to npm. Once it is, you will be able to run it directly with `npx @diegoferreyra/substrate <command>` without any installation steps.
</Note>

## Install from source

<Steps>
  <Step title="Clone and build">
    Clone the repository and build the binary from source.

    ```sh theme={null}
    git clone https://github.com/42pe/substrate.git
    cd substrate
    pnpm install
    pnpm build
    ```
  </Step>

  <Step title="Link the binary globally">
    Add `substrate` to your PATH by creating a global link.

    ```sh theme={null}
    pnpm link --global
    ```

    After this step, the `substrate` command is available in any directory. When Substrate reaches npm, the equivalent will be `npx @diegoferreyra/substrate <command>`.
  </Step>

  <Step title="Install the agent skill">
    Copy the packaged agent skill into Claude's skills directory.

    ```sh theme={null}
    substrate install-skill
    ```

    This writes to `~/.claude/skills/substrate` and stamps the skill with the binary's current version. The skill teaches your agent conventions like calling `whoami` first, using optimistic concurrency, and reading the policy envelope — so you do not have to restate those instructions every session. See [MCP setup](/getting-started/mcp-setup) for details.
  </Step>
</Steps>

## Verify the installation

Run the help command to confirm `substrate` is on your PATH and check the reported version:

```sh theme={null}
substrate --help
```

The output opens with the version line — for example, `Substrate v0.7.0 — …`. There is no separate `--version` flag in v0.7.0.

Inside any project that already has a `.substrate/` directory, you can run a deeper health check:

```sh theme={null}
substrate diagnose
```

This prints your environment details and the substrate health status for that project, and exits with a non-zero code if it finds problems.

<Tip>
  Run `substrate diagnose` any time you see unexpected behavior. It is the fastest way to rule out environment and path issues.
</Tip>

<Warning>
  If `substrate` is not found after linking, check that your global pnpm bin directory is on your `PATH`. Run `pnpm bin --global` to find the directory and add it to your shell profile if needed.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="bolt" href="/getting-started/quickstart">
    Initialize a board in your project and start the local inspector.
  </Card>

  <Card title="Upgrading" icon="arrow-up-circle" href="/operations/upgrading">
    Pull the latest source, rebuild, and re-link to upgrade an existing install.
  </Card>
</CardGroup>