# Install Zinn

Zinn is published on npm as two packages: the CLI, [@zinn-dev/cli](https://www.npmjs.com/package/@zinn-dev/cli), and the core library at [@zinn-dev/core](https://www.npmjs.com/package/@zinn-dev/core).

## Requirements

The CLI and core run on [Node.js](https://nodejs.org/) 24.15.0 or newer. Core also runs on Bun, and the CLI can run on Bun through `bunx`.

On a Node.js 24 release older than 24.15.0, npm installs Zinn with an engine warning, and every command that opens the database prints an `ExperimentalWarning` about SQLite to stderr. Output on stdout, including `--json`, is unaffected.

## Install the CLI

```sh title="Install the CLI"
npm i -g @zinn-dev/cli
```

Check that the `zinn` command is available:

```sh title="Check the installed version"
zinn --version
```

The [quick start](/docs/quick-start) creates a first project and task.

### Run the CLI on Bun

The `zinn` command runs on Node.js. To run the CLI on Bun, even where Node.js is installed, use `bunx --bun` and put the Zinn command after the package name:

```sh title="Run the CLI on Bun"
bunx --bun @zinn-dev/cli --help
```

Bun's documentation explains [how `--bun` overrides a Node.js shebang](https://bun.com/docs/pm/bunx#shebangs).

## Use with coding agents

Choose either setup for your coding agent:

### Skill

Install the [Zinn workflow skill](https://github.com/yethranayeh/zinn/blob/main/packages/cli/skills/zinn/SKILL.md). It covers picking up work, keeping task context, recording follow-ups, and handing off for review.

```sh title="Install the agent skill"
zinn skill install
```

The command installs the skill bundled with your Zinn CLI, so the skill matches the commands your CLI has. It installs globally for use across repositories and applies where the user or repository uses Zinn. The installer is the [open-source skills CLI](https://github.com/vercel-labs/skills), which the command runs through `npx`.

### Repository rule

Add this line to your `AGENTS.md` or `CLAUDE.md`, then let the agent discover commands through `zinn --help`:

This repository uses Zinn for work tracking. Before substantial work, on resume, and before finishing, check the relevant task and keep it current. Use `zinn --help` to discover commands.

## Add core to a project

```sh title="Add core to a project"
npm i @zinn-dev/core
```

See the [Core library guide](/docs/core) for a runnable example with database configuration.

## Upgrade

Save a backup of the database first:

```sh title="Back up the database"
zinn backup
```

Then install the latest CLI. It brings the core release it was built with:

```sh title="Upgrade the CLI"
npm i -g @zinn-dev/cli@latest
```

If you installed the agent skill, update it separately:

```sh title="Update installed agent skills"
npx skills update -g
```

After switching Node versions or package managers, run `zinn skill install` again instead. The CLI then lives in a new folder, and the command installs the skill from there.

In a project that uses core, upgrade it there:

```sh title="Upgrade core in a project"
npm i @zinn-dev/core@latest
```

Name `@latest`: npm saves core with a `^0.x` range, which stays within one minor release.

A newer release upgrades an older database the first time it opens it, saving a backup first.

> **Upgrade the CLI and core together**
>
> Older releases open an upgraded database read-only. For example, a newer CLI upgrades the database, then a project that still depends on an older core opens it. When the CLI and core share a database, upgrade them together.

See [Data and backups](/docs/data) for backup, restore, and database-upgrade behavior.

## Uninstall

Uninstalling the CLI also removes the core it brought:

```sh title="Uninstall the CLI"
npm uninstall -g @zinn-dev/cli
```

In a project that uses core, remove it there:

```sh title="Remove core from a project"
npm uninstall @zinn-dev/core
```

Uninstalling leaves your data in place. The Zinn directory holds the database, backups and settings. It is `~/.zinn` unless `ZINN_DIR` or a [settings file](/docs/settings) chooses another. Deleting it removes every project and backup.