# Getting started

Source: https://tapid.dev/docs/getting-started

Install Tapid from the public release, run a supported package flow, and inspect the result.

Install Tapid from the public release installer, then use it in a normal `package.json` project. Current installers select an archive through the Tapid release record, authenticate that record through a native verifier, and check archive size and SHA-256 before installation. GitHub hosts the immutable release assets. These examples target published v0.0.13; read [Compatibility](https://tapid.dev/docs-markdown/compatibility/content.md) before evaluating a project.

## Install Tapid

### macOS and Linux

```bash
$ curl -fsSL https://tapid.dev/install.sh | bash
```

The Unix installer places Tapid in `~/.local/bin` and adds that directory to `PATH` when needed. Open a new terminal if another process does not see the change, then check the installed version:

```bash
$ tapid --version
```

### Windows PowerShell

```powershell
$ iwr -useb https://tapid.dev/install.ps1 | iex
```

The PowerShell installer places Tapid in `$HOME\.local\bin` and updates your user `PATH` when needed. Open a new PowerShell window if another process does not see the change, then check the installed version:

```powershell
$ tapid --version
```

### Optional: inspect the installer before it runs

The one-line commands above download and execute the current installer. They do not let you review the script first. Use the commands below if you want to inspect what you are about to run or pass options such as a specific release.

On macOS and Linux:

```bash
$ installer="$(mktemp)"
$ curl -fsSL https://tapid.dev/install.sh -o "$installer"
$ less "$installer"
$ sh "$installer"
$ rm -f "$installer"
```

On Windows PowerShell:

```powershell
$ $installer = Join-Path $env:TEMP "tapid-install.ps1"
$ Invoke-WebRequest https://tapid.dev/install.ps1 -OutFile $installer
$ Get-Content $installer
$ & powershell.exe -NoProfile -ExecutionPolicy Bypass -File $installer
$ Remove-Item $installer
```

The [latest release page](https://tapid.dev/docs-markdown/releases/latest/content.md) also lists every native archive, `SHA256SUMS`, and the release notes fetched from GitHub during the website build.

## Evaluate an existing project

Preserve `package.json`, the existing package-manager lock and installation before testing Tapid in a separate checkout. Check [Compatibility](https://tapid.dev/docs-markdown/compatibility/content.md) for supported specs, peer placement, workspaces and required build hooks.

Choose [npm lock import](https://tapid.dev/docs-markdown/commands/import-package-lock/content.md) if you need to preserve supported npm lockfile v3 selections. An ordinary first `tapid install` resolves Tapid's supported graph; it does not import npm's selections automatically. An existing npm-managed `node_modules` needs a verified backup and removal from the activation path before Tapid installs its managed tree. See [Troubleshooting](https://tapid.dev/docs-markdown/troubleshooting/content.md).

Keep the existing package manager's deployment path until your application checks and rollback rehearsal pass. A successful install alone does not establish compatibility.

## Install a package

Create a project and install one supported package:

```bash
$ mkdir demo
$ cd demo
$ tapid init
$ tapid i is-char
```

Quote package specs containing `*`, `^`, comparison operators or other shell syntax, for example `tapid add 'react@^19.0.0'`. This keeps the shell from expanding or interpreting the requirement before Tapid reads it.

`tapid i <package>` is an alias for `tapid install <package>`. The command adds the dependency to `package.json`, resolves supported transitive dependencies, checks registry-declared integrity, writes `tapid.lock`, stores the verified package tree, and activates managed `node_modules`. Dependency lifecycle scripts are denied by default. Exact approvals support bounded online execution on Linux; see [Dependency scripts](https://tapid.dev/docs-markdown/dependency-scripts/content.md).

An explicit `--allow-unverified-registry-artifacts` compatibility exception can accept locally computed artifact integrity for an online install. It emits a warning, cannot be combined with `--offline` or `--frozen`, and produces provenance that frozen replay rejects. See [the install command](https://tapid.dev/docs-markdown/commands/install/content.md) before using it.

Run `tapid install` in an existing project to install its declared dependencies. It replays a matching lock or preserves compatible locked selections while resolving manifest changes. Once the lockfile and verified store are present, replay the same graph without changing the lockfile:

```bash
$ tapid install --offline --frozen
```

Offline frozen replay checks the manifest, lockfile, and stored package data before activation. It does not resolve the graph again.

## What Tapid checks

Tapid keeps the familiar `package.json` and registry workflow, but records more of the install boundary. During an online install it requires registry metadata to declare the SHA-512 used for the package archive. It records the exact registry, version, artifact digest, and dependency edges in `tapid.lock`, then materializes managed `node_modules` only after those inputs validate.

## What the current client can answer

* Which exact package versions and dependency edges were selected?
* Did registry metadata declare the integrity used to authenticate each artifact?
* Does the lockfile's manifest and verified store content validate before activation?
* Were managed `node_modules` files created?
* Can an explicit root script run with forwarded arguments?
* Does the child process exit code return to the caller?
* Were dependency lifecycle scripts denied or covered by exact approvals?

The default online registry path fails closed when required metadata or declared integrity is missing. JSR support remains experimental and fails closed unless metadata supplies an HTTPS npm artifact and valid SHA-512 integrity.

## Run a project script

Starting with v0.0.10, `tapid run <script>` requires Node.js, a checked-in `tapid.toml`, and an exact script profile. Published v0.0.13 includes experimental macOS Restricted, Linux Restricted and ManagedTree, and limited read-only Windows containment. Linux ManagedTree requires delegated cgroup v2 resource controls and private namespaces. Platform and configuration acceptance remain bounded. Unsupported containment fails before launch.

Read [tapid run](https://tapid.dev/docs-markdown/commands/run/content.md) to configure filesystem, network, and environment permissions before executing project code. Forwarded arguments follow `--`. Restricted execution does not guarantee complete descendant cleanup or that arbitrary code is safe.

## Upgrade Tapid

Use the in-client upgrade command for existing managed installations:

```bash
$ tapid upgrade --dry-run
$ tapid upgrade
```

For clients through v0.0.9, rerun the public installer. See [tapid upgrade](https://tapid.dev/docs-markdown/commands/upgrade/content.md) for signed-record verification, replay protection and recovery limits.

For automated use, read [Using Tapid with AI agents](https://tapid.dev/docs-markdown/ai-agents/content.md). The [command reference](https://tapid.dev/docs-markdown/commands/content.md) distinguishes released behavior from [changes in v0.0.13](https://tapid.dev/docs-markdown/development/content.md).

## Current status and direction

**Manifest validation**

**Implemented**

`package.json` identity is validated before project work.

**Lockfile replay**

**Implemented**

Frozen replay checks pinned inputs and can hydrate missing artifacts. Offline replay needs a complete verified store.

**Node-compatible linking**

**Implemented**

Managed package files and executable metadata are materialized for the supported path.

**Root scripts**

**Implemented with constraints**

An exact script policy is required. Platform-specific containment and acceptance remain limited.

**Package-spec installation**

**Implemented with constraints**

`tapid install is-char` and `tapid i is-char` add and install supported npm packages.

**Full npm compatibility**

**In progress**

Aliases, bounded workspaces, direct-root peer checks and explicit private routing are implemented. Tags, full peer placement and complete npm semantics remain unsupported.

**Stable release installation**

**Available**

Current installers authenticate the release record and verify archive size and checksum. Use tapid upgrade for existing managed installations.

**Registry publishing and policy**

**Future direction**

Registry services, provenance verification, policy enforcement, and agent integration are not current client guarantees.

Continue with [Commands](https://tapid.dev/docs-markdown/commands/content.md) for the CLI surface, or read [Contributor](https://tapid.dev/docs-markdown/contributor/content.md) if you are changing Tapid itself.

## Continue with a project workflow

Use [add, remove and update](https://tapid.dev/docs-markdown/commands/content.md) to change dependency declarations. Read [Workspaces](https://tapid.dev/docs-markdown/workspaces/content.md) for member links, [Private registries](https://tapid.dev/docs-markdown/private-registries/content.md) for scoped credentials, and [Troubleshooting](https://tapid.dev/docs-markdown/troubleshooting/content.md) for transaction outcomes. `tapid license` prints the Apache-2.0 license offline.

Production support is not currently available. Preserve an existing project's npm lock and rollback path while evaluating an exact Tapid release in staging.