CLI and CI

​

Install and sign in

npx artbucket login app.artbucket.io    # or your server: assets.example.com, http://localhost:3000
npm install -g artbucket                # to keep it, rather than npx each time

​

The brand a command acts on

​

brand pull

artbucket brand pull brand --brand acme --assets

  wrote   brand.yaml
  wrote   rules/color.yaml
  wrote   pages/overview.yaml
  wrote   assets/logo.svg
acme is in brand

• Only files whose meaning changed are written: one that says the same keeps its comments and layout.
• A file of rules/ or pages/ the brand no longer has is removed.
• A file you named .yml keeps its name.
• --assets gives every asset the brand points at a path under assets/, named after its filename, and downloads the ones whose bytes the folder doesn’t already hold. A folder whose assets/ already holds files pulls this way without the flag.
• A file already in assets/ keeps its path, wherever it sits, matched by the SHA-256 of its bytes: references to it stay paths, never ids.

​

brand diff

artbucket brand diff brand

! pages/logo.yaml:12: sections[1]: a second panel ground in a row runs into the one before; make one of them plain
  ~ color.primary  #1f6feb -> #1a5fd0
  + color.accent  #ff7a45
  ~ page color
  > page type (moved)
  ~ theme: radius
(dry run: nothing written)

pages/color.yaml:6: sections[0].keys[0]: no rule "color.nope"; this brand has color.primary, color.ink

  + assets/hero.jpg (push uploads it)
The rest of the diff shows once those are in the library: push uploads them first

​

brand push

artbucket brand push brand --publish --note "Bluer primary"

  uploaded assets/hero.jpg
  ~ color.primary  #1f6feb -> #1a5fd0
version 14, published

1. Hashes every file under assets/, checks the files, and uploads each file they point at that the library doesn’t have yet.
2. Writes the brand as one version of its history, so it is undone like any other edit, or prints nothing changed.
3. Publishes, if asked.

​

What a push overwrites

  ~ color.primary  #1a5fd0 -> #1f6feb

​

From CI

name: Brand
on:
  pull_request:
    paths: ["brand/**"]
  push:
    branches: [main]
    paths: ["brand/**"]
env:
  ARTBUCKET_URL: https://app.artbucket.io
  ARTBUCKET_KEY: ${{ secrets.ARTBUCKET_KEY }}
jobs:
  brand:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v5
        with:
          node-version: 22
      - if: github.event_name == 'pull_request'
        run: npx --yes artbucket brand diff brand --brand acme
      - if: github.event_name == 'push'
        run: npx --yes artbucket brand push brand --brand acme --note "$(git log -1 --format=%s)"

brand-check:
  image: node:22
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes: ["brand/**/*"]
  script:
    - npx --yes artbucket brand diff brand --brand acme

brand-push:
  image: node:22
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      changes: ["brand/**/*"]
  script:
    - npx --yes artbucket brand push brand --brand acme --note "$CI_COMMIT_TITLE"

• ARTBUCKET_URL is your own server when you host one. On GitLab, ARTBUCKET_URL and ARTBUCKET_KEY are CI/CD variables, the key masked.
• With --note, each push to main is released with its commit’s first line. Leave --note out to update the draft only, and release it from the app.
• The check on a pull request reads the brand with the key, so it needs the secret: pull requests from forks, which get no secrets, can’t run it.
• A pull request that adds a file under assets/ passes the check: diff lists the file, and the push on main uploads it.
• A CI push has no sync base, so the repository is the source of truth: edits made in the app are undone by the next push. For both sides at once, use a Git integration.

​

Without the CLI