Back to home Full workflow

Read the history first. Then create the next tag.

The Tagsmith workflow starts with a local inspection. Preview only when the convention is clear; when it is ambiguous, the maintainer makes intent explicit. Creation and publication are separate, deliberate steps.

Before you start

Run these commands inside a Git repository with Node.js 22+. Every command is ready to copy; the workflow does not depend on remote state.

01
Inspect

Start with the local tag history you know.

Begin with list. Tagsmith orders tags semantically and flags mismatches, unparseable versions, and duplicates. Before a release, use audit to check the complete history, configured local guardrails, and the artifact versions stored with historical tags. It never repairs history automatically.

Try it safely

npx @carllee1983/tagsmith list

This reads and evaluates local history only; it does not change the repository.

02

Does the history make one convention clear?

Convention clear

Keep the inference and preview.

A consistent SemVer-style history can follow the zero-configuration path. The next step calculates only; it does not create a tag.

Continue to preview
Convention ambiguous

Let the maintainer define intent.

Mixed, ambiguous, and non-SemVer history is not guessed or corrected automatically. Record the team convention, then inspect again.

Set the convention

npx @carllee1983/tagsmith init

Commit the generated .tagsmith.json, then run list again.

See the configuration shape
03
Preview

Once intent is clear, preview the next version.

next calculates the next tag from the active convention and known local history. It creates no tag and makes no remote request.

Preview only

npx @carllee1983/tagsmith next

For a minor or major release, add the same --level here and when creating. With a commit policy, --from-commits shows the matching rule behind the recommendation.

04
Create

After the preview, confirm push: false before creating locally.

Before creation, Tagsmith validates again against the explicit convention and known local history. If the proposal does not fit, it stops instead of selecting a resolution for you. When the artifact-version guardrail is enabled, --enforce-policy also stops creation if the target commit’s package.json is missing or its version does not match.

New configuration defaults to push: false. create honours the selected tag line's setting: when it is false, the tag stays local; when it is true, this command publishes it.

Create after checking push

npx @carllee1983/tagsmith create

Copy this only after confirming the selected tag line keeps push: false.

05
Publish

Remote publication is a separate, intentional decision.

Whether, when, and how a tag is pushed belongs to the team’s existing Git hosting and release workflow. Tagsmith provides local validation and predictable creation; it does not replace remote conflict handling, access control, or repository-wide enforcement.

For automation

Give surrounding workflows the evaluation result.

--json lets CI and scripts consume Tagsmith’s convention evaluation. Your automation remains responsible for the next action.

npx @carllee1983/tagsmith next --json
Need more configuration?

Start with one tag line.

SemVer is the default evaluation path. Add CalVer, build numbers, multiple tag lines, artifact-version checks, commit policy, or optional local guardrails only after the need is clear.

Read the configuration reference