# tapid install

Source: https://tapid.dev/docs/commands/install

Replay or install project dependencies through the supported paths.

## Version scope

This page targets published v0.0.13. It includes lock-preserving installation, pinned frozen downloads, npm lock import, bounded workspaces and exact dependency-hook approvals. [Compatibility](https://tapid.dev/docs-markdown/compatibility/content.md) records remaining limits. Imported locks have separate verification-receipt behavior; read [their guide](https://tapid.dev/docs-markdown/commands/import-package-lock/content.md).

## Syntax

```text
tapid install [PACKAGE] [OPTIONS]
```

The install command can add one package or install the dependencies already declared in `package.json`. With a matching lock, ordinary installation replays its selections without registry metadata requests. When inputs change or no lock exists, it resolves the supported npm-compatible subset, requires registry-declared integrity, stores verified package trees, and activates managed `node_modules`. Changed manifests retain compatible locked selections while resolving necessary changes; `tapid update` explicitly refreshes the graph.

```bash
$ tapid install is-char
$ tapid i is-char
$ tapid install
```

Package arguments support unscoped names, scoped names, exact versions, supported ranges, npm aliases, and the `npm:` and `jsr:` prefixes where the underlying registry metadata satisfies tapid's current trust and compatibility requirements.

## What an online install changes

With matching project inputs, ordinary installation replays the existing lock and can fetch missing pinned artifacts. It does not refresh every selected version. Imported locks preserve their graph and can gain verification receipts.

When resolution is needed, Tapid:

1. reads and validates the root and workspace manifests;
2. adds the requested package to `dependencies` when a package argument is present;
3. retains compatible locked selections while resolving necessary dependency changes;
4. downloads and verifies package archives using registry-declared SHA-512 integrity;
5. records the resulting lock and verified package trees; and
6. activates managed `node_modules` through the recoverable lifecycle transaction.

The command prints `Installed N package(s)` on success. Dependency hooks are denied by default. Exact checked-in approvals can build derived trees on supported Linux ManagedTree; read [Dependency scripts](https://tapid.dev/docs-markdown/dependency-scripts/content.md) before authorizing execution. Frozen and offline replay never execute hooks.

Pre-commit failures restore prior project and store state when rollback succeeds. Committed changes with cleanup pending and failed recovery need different responses; read [Troubleshooting](https://tapid.dev/docs-markdown/troubleshooting/content.md) before retrying.

When a package argument is present, it cannot be combined with `--offline` or `--frozen`. Those modes replay an existing project and do not resolve a new package.

## Project replay

Use offline or frozen mode to replay an existing project lockfile without registry metadata resolution:

```bash
$ tapid install --offline --frozen --project-dir ./example
```

The project must provide valid matching manifests and a compatible `tapid.lock`. `--offline` requires every applicable verified source and derived tree in the store. Without `--offline`, frozen installation can fetch missing pinned source archives and verify their SHA-512 integrity and locked tree digests. It never rebuilds approved derived outputs. Tapid validates replay inputs before activating managed `node_modules`.

The repository fixture verifies deterministic replay, managed files, executable metadata, root-script behavior, argument forwarding, exit-code propagation, and dependency lifecycle suppression.

## Install modes

* Ordinary install replays a matching lock. Changed manifests preserve compatible locked selections while resolving necessary changes. Registry-declared integrity is required unless the explicit online compatibility exception is enabled.
* `--offline` forbids downloads and metadata resolution. It requires matching manifests and every applicable verified source and derived tree.
* `--frozen` preserves selections and ordinary lock bytes without metadata resolution. It can hydrate missing trees from pinned HTTPS URLs with registry-declared integrity and tree-digest verification. Imported locks can record verification receipts. Combine it with `--offline` to forbid downloads.
* `tapid ci` preserves ordinary manifest and lock bytes and fetches missing pinned sources. It rejects imported schema-8 locks and never rebuilds derived outputs. Read [tapid ci](https://tapid.dev/docs-markdown/commands/ci/content.md).

Corrupt stored trees, changed routing or target contexts, and missing integrity provenance fail closed. Cold hydration needs pinned URLs; locks missing those URLs require deliberate `tapid update` and review. Unsupported or noncanonical locks need a verified backup and deliberate removal before generating a replacement. Ordinary install does not silently repair them.

## Options

```text
--offline
--frozen
--project-dir PATH
--workspace NAME
--store-dir PATH
--registry-fixture PATH
--allow-unverified-registry-artifacts
```

`--registry-fixture` is for tests and air-gapped development. It is not a production registry mirror or authentication feature.

`--allow-unverified-registry-artifacts` is an explicit compatibility escape hatch. It emits a warning, records locally computed integrity provenance, cannot be combined with `--offline` or `--frozen`, and produces a lockfile that frozen replay rejects.

`--workspace NAME` selects a member while retaining root-owned lockfile and activation. See [Workspaces](https://tapid.dev/docs-markdown/workspaces/content.md).

`--project-dir` selects the project directory and defaults to the current directory. `--store-dir` selects the verified package store instead of the platform default. `--registry-fixture` supplies a local JSON registry fixture for tests and air-gapped development; it is not a registry mirror or authentication mechanism.

## Common failures

* A missing or invalid `package.json` stops the install before dependency work begins.
* Missing registry-declared integrity fails the default online path unless the compatibility exception is explicit.
* Offline replay fails when the matching lock, manifest digest or verified trees are missing. Frozen replay also fails if missing trees cannot be verified from pinned inputs.
* A changed manifest is rejected during replay rather than silently updating the lockfile.
* Unsupported package specifications, registry metadata, or dependency graph shapes fail closed instead of being guessed.

## Current limits

Published v0.0.13 implements a bounded npm-compatible subset. Dist-tags, git/file dependencies, automatic or nested peer placement, full workspace glob semantics and several optional-dependency behaviors remain unsupported. Scoped private routing uses explicit Tapid configuration, not implicit `.npmrc` behavior. JSR requires an HTTPS npm artifact and valid SHA-512 integrity; live JSR behavior remains unverified.

An npm alias can preserve a separate local import name:

```bash
$ tapid add 'local@npm:is-char@1.1.11'
```

Registry routing uses the actual target package. Full npm compatibility and production support are not established. Installation verifies supported identity and integrity rules; it does not sandbox code when your application imports it. Read [Compatibility](https://tapid.dev/docs-markdown/compatibility/content.md) and [Private registries](https://tapid.dev/docs-markdown/private-registries/content.md).