Quick start

Four minutes, start to finish. You need Node 22 or newer and a git repository with at least one tag.

1. Detect your brand

npx shipseal@latest init

This reads your package.json, README, stylesheets and logo files, then writes.shipseal/brand.json and .shipseal/config.json. It prints where every value came from and renders one sample card so you can see the result immediately.

Read the output. Any colour Shipseal could not find in your project is reported as a built-in default. Those are not your brand, so open brand.json and set them.

Commit both files. They belong in the repository.

2. Generate a pack

npx shipseal@latest release

Images land in .shipseal/output/<tag>/ alongside a manifest.json listing every fact and where it came from. To see the facts without rendering anything:

npx shipseal@latest release --dry-run

3. Automate it

Add .github/workflows/shipseal.yml:

name: Shipseal
on:
  release:
    types: [published]

permissions:
  contents: write

jobs:
  visuals:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: akii09/shipseal@v0.0.6
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

fetch-depth: 0 is required. Checkout uses a shallow clone by default, which leaves Shipseal without the history and tags it needs. shipseal doctor warns you if this is wrong.

Publish a release. The images are generated and attached to it automatically.

4. Ignore the output

echo ".shipseal/output/" >> .gitignore

If something looks off

npx shipseal@latest doctor

It checks Node, git, shallow clones, the brand file, fonts, the logo and the renderer, and tells you how to fix each failure. See the manifest reference for tracing a wrong value.