---
description: Install Verso, initialize discovery, validate the repository, and preview the exact release plan.
---

# Get ready for the first release

## Requirements

Verso requires Node.js 22.18 or newer and supports these platforms:

| Operating system | CPU          |
| ---------------- | ------------ |
| macOS            | arm64 or x64 |
| Linux (GNU)      | arm64 or x64 |
| Windows          | x64          |

The target repository also needs Git, at least one supported package manifest, and a named branch
with an upstream. A real release is rejected when the local branch is behind that upstream.

## Install Verso

Add Verso at the project root with your preferred package manager:

<InstallTabs dev packageName="@amamo/verso" />

The reference pages write commands as `verso ...` so their arguments stay independent of a package
manager. Invoke the locally installed executable through your package manager or an existing project
task.

## Decide whether a config is needed

For a single package, a root `package.json`, `package.json5`, `package.yaml`, or `package.yml` is
enough. With no explicit `--config`, Verso uses built-in single-package defaults.

For a workspace, generate `verso.toml`:

```sh
verso init
```

The initializer selects workspace mode only when it finds `packages/*/package.json`; otherwise it
creates a single-package config. Override that narrow detection when necessary:

```sh
verso init --workspace
verso init --single
```

`init` refuses to replace an existing file. Use `--force` only when replacing it is intentional.

<Callout variant="note" title="Check whether the workspace root has a version">
  The generated workspace config includes the root package. If the root `package.json` only
  describes the workspace and should not share the released version, set `workspaces.include_root =
  false` and keep `workspaces.patterns` explicit and nonempty.
</Callout>

## Inspect release readiness

Run the first check through the package manager that installed Verso:

<Tabs defaultValue="pnpm">
  <Tab label="pnpm" value="pnpm">

```sh
pnpm exec verso doctor
```

  </Tab>
  <Tab label="npm" value="npm">

```sh
npm exec --package=@amamo/verso -- verso doctor
```

  </Tab>
  <Tab label="yarn" value="yarn">

```sh
yarn exec verso doctor
```

  </Tab>
  <Tab label="bun" value="bun">

```sh
bunx --no-install verso doctor
```

  </Tab>
</Tabs>

`doctor` checks config loading, package discovery, the current version, shared package and Cargo
versions, the changelog parent directory, and the named branch's upstream. It returns a nonzero exit
status when any check fails. The remaining examples use `verso` as shorthand for the same local
executable. Automation can consume the checks as JSON:

```sh
verso doctor --json
```

## Preview one exact version

Start with an explicit target so the preview is reproducible:

```sh
verso --dry-run --version 1.4.0
```

The plan lists version files, the optional changelog, configured hooks, warnings, commit and tag
templates, and the exact shape of the Git commands. It performs no writes, hooks, commits, tags, or
pushes. JSON output is available only in dry-run mode:

```sh
verso --dry-run --version 1.4.0 --json
```

<Callout variant="warning" title="Hook commands appear in previews">
  Do not embed tokens or passwords in `verso.toml`. Dry-run output deliberately includes each hook
  command so the release plan is inspectable.
</Callout>

## Run the release

Interactive mode offers stable and prerelease choices, then asks before files, commit, tag, and push:

```sh
verso
```

Automation should provide the exact SemVer and opt into all confirmations:

```sh
verso --version 1.4.0 --yes
```

`--yes` skips confirmations; it never chooses a version. Read [Release workflow](/release-workflow/)
before automating a repository with hooks or a relaxed worktree policy.