### Worked example: full prerelease ladder with tagsmith tag

Source: https://tagsmith.site/docs/versioning

Full ladder example starting from no tags with `initialVersion` 0.0.0 and channels alpha, beta, rc, stable. Shows how to cut a fresh minor line, continue a prerelease, promote to beta and rc, and promote to stable; each `tag` invocation requires the channel's `dependsOn` chain to be satisfied at the same base.

```sh
# Cut alpha.1 at a fresh minor line.
tagsmith tag --target app --channel alpha --bump minor          # → 0.1.0-alpha.1

# Continue alpha line.
tagsmith tag --target app --channel alpha --bump prerelease     # → 0.1.0-alpha.2

# Promote to beta. Same base.
tagsmith tag --target app --channel beta --version 0.1.0-beta.1 # → 0.1.0-beta.1

# Cut rc against beta.
tagsmith tag --target app --channel rc --version 0.1.0-rc.1     # → 0.1.0-rc.1

# Promote to stable. dependsOn rc → highest same-base rc must exist.
tagsmith tag --target app --channel stable --bump minor         # → 0.1.0
```

--------------------------------

### AI agent setup instruction

Source: https://tagsmith.site/docs/setup-with-ai

Copy this instruction into an AI coding agent (e.g., Claude Code, Cursor, Codex, opencode) from inside the repository to begin setup. The agent should fetch the referenced page and follow its LLM-only instructions.

```text
Follow the LLM-only instructions at https://tagsmith.site/docs/setup-with-ai.md to set up Tagsmith in this repository.
```

--------------------------------

### defaults configuration example

Source: https://tagsmith.site/docs/configuration

Example of the `defaults` section. All three fields are required. Targets inherit these values unless overridden. `initialVersion` must be canonical stable SemVer (e.g., `0.0.0`).

```jsonc
"defaults": {
  "tagPattern": "{target}@{version}",
  "tagMessage": "Release {target} {version}",
  "initialVersion": "0.0.0"
}
```

--------------------------------

### git configuration example

Source: https://tagsmith.site/docs/configuration

Example of the `git` section. Both `remote` and `baseBranch` are required. `remote` must be a configured Git remote name (e.g., `origin`), and `baseBranch` must be an unqualified branch name (e.g., `main` or `release/1.x`).

```jsonc
"git": {
  "remote": "origin",
  "baseBranch": "main"
}
```

--------------------------------

### list --json output example

Source: https://tagsmith.site/docs/output

Example output of the `list --json` command. Shows a tag record with fields for tag, target, channel, version, legacy, local, remote, status, commit, and createdAt. `createdAt` is null for lightweight tags and remote-only records.

```json
[
  {
    "tag": "app@1.3.0",
    "target": "app",
    "channel": "stable",
    "version": "1.3.0",
    "legacy": false,
    "local": true,
    "remote": true,
    "status": "local+remote",
    "commit": "0123456789abcdef0123456789abcdef01234567",
    "createdAt": "2026-08-13T12:34:56Z"
  }
]
```

--------------------------------

### Human-mode success output after create

Source: https://tagsmith.site/docs/cli/tag

Example output when `tag` successfully creates and pushes a tag. Shows the tagged version, commit hash, and confirmation flags.

```text
Tagged v1.2.3 (1.2.3) for target app channel stable.
Commit: 012345678901
Created: yes
Pushed: yes
```

--------------------------------

### list output

Source: https://tagsmith.site/docs/output

Example output for the `list` command. Shows a table with tag, target, channel, status, and created timestamp.

```text
tag         target  channel  status        created
tag         app     stable   1.2.3    local+remote  2026-08-13 12:34:56Z
```

--------------------------------

### tag --json output example

Source: https://tagsmith.site/docs/output

Example JSON output from `tag --json` or `tag --dry-run --json`. Shows the resolved target, channel, strategy, version, baseVersion, rendered tag and message, commit SHA, and flags for creation, push, and dry-run. In dry-run with `--push`, `created` and `pushed` are false and there is no `wouldPush` field.

```json
{
  "target": "app",
  "channel": "stable",
  "strategy": "stable",
  "version": "1.2.3",
  "baseVersion": "1.2.3",
  "tag": "v1.2.3",
  "tagMessage": "Release 1.2.3",
  "commit": "0123456789abcdef0123456789abcdef01234567",
  "created": true,
  "pushed": false,
  "dryRun": false
}
```

--------------------------------

### Initialize Tagsmith config

Source: https://tagsmith.site/docs/getting-started

Run inside a Git repo with a clean working tree and a remote called 'origin'. Writes .tagsmith.jsonc at the repo root with example targets and a channel ladder.

```sh
npx tagsmith@latest init
```

--------------------------------

### README note for Tagsmith releases

Source: https://tagsmith.site/docs/setup-with-ai

Optional README note to add after setup, as suggested by the AI agent guidelines. The `<runner>` placeholder should be replaced with the detected package runner (e.g., npx, bunx, pnpm dlx, yarn dlx).

```md
Releases are managed by [Tagsmith](https://tagsmith.site/).
Use `<runner> tagsmith@latest` to create and validate release tags.
```

--------------------------------

### tagsmith list human-mode output example

Source: https://tagsmith.site/docs/cli/list

Example of the human-readable output from `tagsmith list`. The table shows tag, target, channel, version, status, and created columns. The created column shows the local annotated tag's tagger timestamp in UTC; lightweight tags and remote-only tags show a dash.

```text
tag              target  channel  version     status                created
app@1.3.0        app     stable   1.3.0       local+remote          2026-08-13 12:34:56Z
app@1.2.0        app     stable   1.2.0       legacy remote-only    —
app@1.1.0-rc.1   app     rc       1.1.0-rc.1  legacy local-only     2025-04-02 08:15:00Z
```

--------------------------------

### Channel entry example

Source: https://tagsmith.site/docs/configuration

Defines a channel entry with a name, strategy, and optional dependsOn array. The name must match ^[a-z][a-z0-9-]*$ and be unique within the target. The strategy must be "prerelease" or "stable", and dependsOn must reference channels in the same target without self-references or cycles.

```jsonc
{ "name": "rc", "strategy": "prerelease", "dependsOn": ["beta"] }
```

--------------------------------

### Human-mode dry-run output

Source: https://tagsmith.site/docs/cli/tag

Example output when `tag` runs in dry-run mode. Shows the resolved version and commit, and notes that no tag was created and that a push would have occurred if `--push` was provided.

```text
Resolved v1.2.3 (1.2.3) for target app channel stable.
Commit: 0123456789abcdef0123456789abcdef01234567
Dry run: No tag was created.
Because --push was provided, Tagsmith would have pushed the tag.
```

--------------------------------

### Human mode output for tagsmith targets

Source: https://tagsmith.site/docs/cli/targets

Example human-mode output for the targets command. One block per target in config order, separated by a blank line.

```text
web
  path: apps/web
  channels: alpha (prerelease), beta (prerelease, dependsOn: alpha), rc (prerelease, dependsOn: beta), stable (stable, dependsOn: rc)
  tagPattern: {target}@{version}
  tagMessage: Release {target} {version}
  initialVersion: 0.0.0

api
  path: apps/api
  channels: alpha (prerelease), beta (prerelease, dependsOn: alpha), rc (prerelease, dependsOn: beta), stable (stable, dependsOn: rc)
  tagPattern: {target}@{version}
  tagMessage: Release {target} {version}
  initialVersion: 0.0.0
```

--------------------------------

### Error: --bump prerelease requires existing line

Source: https://tagsmith.site/docs/versioning

Error message shown when `--bump prerelease` is used without an existing managed prerelease tag for the target+channel. Start a prerelease line with `--bump major|minor|patch` or `--version` first.

```text
Cannot bump prerelease for <target> <channel>: no existing <channel>
prerelease tag found. Use --bump major, --bump minor, --bump patch,
or --version to start a prerelease line.
```

--------------------------------

### tagsmith with global flags --config and --verbose

Source: https://tagsmith.site/docs/interactive

Example of supplying global flags `--config` and `--verbose` before bare `tagsmith`. These flags apply to whichever command is chosen from the action menu and are never prompted.

```sh
tagsmith --config ./release/tagsmith.jsonc --verbose

```

--------------------------------

### tagsmith targets --json output

Source: https://tagsmith.site/docs/cli/targets

Example --json mode output. Writes the raw parsed config object with original key order preserved. Comments and trailing commas are excluded. $schema is included only if present in the source file. Target-level overrides are included only if present; inherited defaults are not materialized.

```json
{
  "$schema": "https://tagsmith.site/schema/v1.json",
  "configVersion": 1,
  "git": { "remote": "origin", "baseBranch": "main" },
  "defaults": {
    "tagPattern": "{target}@{version}",
    "tagMessage": "Release {target} {version}",
    "initialVersion": "0.0.0"
  },
  "targets": {
    "web": {
      "path": "apps/web",
      "channels": [
        /* ... */
      ]
    },
    "api": {
      "path": "apps/api",
      "channels": [
        /* ... */
      ]
    }
  }
}
```

--------------------------------

### Valid SemVer versions

Source: https://tagsmith.site/docs/configuration

Valid SemVer examples that Tagsmith accepts. Versions must be canonical stable or prerelease without leading 'v', build metadata, or leading zeros. Prerelease counters start at 1.

```text
1.2.3
1.2.4-rc.1
1.2.4-pre-prod.1
1.0.0-alpha.42
```

--------------------------------

### Configure targets with channels and dependsOn

Source: https://tagsmith.site/docs/configuration

Defines a target named 'web' with a path and a channel chain: alpha, beta, rc, and stable. The stable channel is required exactly once per target. Channels with dependsOn create a release order; here beta depends on alpha, rc on beta, and stable on rc.

```jsonc
"targets": {
  "web": {
    "path": "apps/web",
    "channels": [
      { "name": "alpha", "strategy": "prerelease" },
      { "name": "beta",  "strategy": "prerelease", "dependsOn": ["alpha"] },
      { "name": "rc",    "strategy": "prerelease", "dependsOn": ["beta"]  },
      { "name": "stable","strategy": "stable",     "dependsOn": ["rc"]    }
    ]
  }
}
```

--------------------------------

### Validate config with npx tagsmith@latest targets

Source: https://tagsmith.site/docs/setup-with-ai

Validate the generated Tagsmith configuration after setup. If anything is wrong, Tagsmith prints the exact field and reason.

```sh
npx tagsmith@latest targets
```

--------------------------------

### tagsmith init command synopsis

Source: https://tagsmith.site/docs/cli/init

Shows the basic usage of `tagsmith init` and its flag combinations: `--force` to overwrite an existing config, `--dry-run` to print template bytes without writing, and both together.

```sh
tagsmith init
tagsmith init --force
tagsmith init --dry-run
tagsmith init --dry-run --force
```

--------------------------------

### Preview next tag with dry-run

Source: https://tagsmith.site/docs/getting-started

Runs the full preflight and skips create/push. The --json payload has the same shape as a real run with created: false, pushed: false, dryRun: true.

```sh
npx tagsmith@latest tag --channel stable --bump patch --dry-run --json
```

--------------------------------

### tagsmith validate human-mode success output

Source: https://tagsmith.site/docs/cli/validate

Example of the human-mode success output from tagsmith validate, showing the validated tag, target, channel, commit, remote, base branch, and valid status.

```text
Validated v1.2.3 (1.2.3) for target app channel stable.
Commit: 012345678901
Remote: origin
Base branch: main
Valid: true
```