Skip to content

CLI and CI

The artbucket CLI reads and writes a brand folder through the sync API, and uploads the files under assets/ the library doesn’t have yet. It works against any Artbucket server.

The CLI is the artbucket package on npm, for Node 22 and later:

Terminal window
npx artbucket login assets.example.com --scope write # your server; http://localhost:3000 in full
npm install -g artbucket # to keep it, rather than npx each time

login signs in through the browser and keeps a key in ~/.config/artbucket/credentials.json, with that server as the default. Pushing a brand edits it, so ask for write: without --scope, login asks for propose, what an agent gets. The consent screen never offers more than you have. artbucket logout forgets the key; disconnect it on the Connections page to revoke it.

Without signing in, two variables say where and as whom:

Variable
ARTBUCKET_URL The server, e.g. https://assets.example.com. Wins over the one login saved
ARTBUCKET_KEY An API key (ab_...). It decides the project. Wins over the saved one

A key for CI is made by a project admin, in the app (Connections) or with POST /api/v1/keys. Pushing takes write on the project; --publish also takes sharing, which a grant can switch off.

Without Node, run the image: ghcr.io/pwnera/artbucket/cli, tagged with each release like the app’s (1.7.0, 1.7, 1, latest). It runs artbucket on the folder mounted at /work, and keeps the key login saves in /config: a named volume there keeps you signed in between runs.

Terminal window
docker run --rm -it -v artbucket:/config ghcr.io/pwnera/artbucket/cli login assets.example.com
docker run --rm -v artbucket:/config -v "$PWD":/work ghcr.io/pwnera/artbucket/cli brand pull brand --brand acme

Or, without the volume, pass -e ARTBUCKET_URL -e ARTBUCKET_KEY.

  • login can’t open a browser from the container: open the link it prints.
  • localhost is the container’s own: a server on your machine is http://host.docker.internal:3000 (on Linux, add --add-host host.docker.internal:host-gateway).
  • The image runs as uid 1000. On Linux, where files brand pull writes keep that owner, add --user "$(id -u):$(id -g)", with -e ARTBUCKET_KEY rather than the volume.

Every brand command acts on the brand --brand names, or else the one the slug: in the folder’s brand.yaml names. Never the project’s default: a folder pushed without either is refused. pull writes slug:, so after the first pull the folder says which brand it is.

The folder is the command’s first argument, brand when left out.

Terminal window
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

Writes the brand as files into the folder:

  • Only files whose meaning changed are written: one that says the same keeps its comments and layout.
  • A file you changed since the last pull or push is never written over or removed: pull refuses and names it. Push it first (push keeps what changed in the app since), then pull; or pull with --force to take the brand’s. Before the folder’s first pull, the files git holds uncommitted count as yours.
  • 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.

Without --assets and with an empty assets/, assets are written as asset ids, unless the brand’s Git integration holds them as files.

Terminal window
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: lede
~ palette (palette, "Blue leads, white gives it room"): keys
+ text-2 (text, "When to use the accent")
> page type (moved)
~ theme: radius
(dry run: nothing written)

What a push would change, and every problem in the files, writing nothing. Lines start with + (added), - (removed), ~ (changed) or > (moved); under a changed page, its sections that changed, by id, with what they are and which of their fields changed. ! is a warning or a conflict. It exits 1 on any error in the files, each printed at its file and line:

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

A file under assets/ the server doesn’t have yet is not a problem: push uploads it. diff lists it and exits 0, and shows the rest of the change once the file is in the library:

+ assets/hero.jpg (push uploads it)
The rest of the diff shows once those are in the library: push uploads them first
Terminal window
artbucket brand push brand --publish --note "Bluer primary"
uploaded assets/hero.jpg
~ color.primary #1f6feb -> #1a5fd0
version 14, published

Takes the brand from its files:

  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.
Flag
--brand acme The brand, when brand.yaml has no slug:
--create Make the brand when there is none by that slug
--publish Release it after, without a note
--note "..." Release it after, with this note. A note always publishes, --publish or not
--replace Take the files whole, even where the brand has a sync base to merge from
--dry-run Check and print what would change, write nothing: the same as brand diff

A push merges with the app’s edits from a base: the files both sides last agreed on. The CLI keeps one for each folder it pulls into or pushes from (beside its key, in ~/.config/artbucket/bases/), and a Git integration records one at each commit. An edit made in the app since is kept, piece by piece: a rule, a page’s own field, a section. Where both sides changed the same piece, the files win, and push says so:

! page overview: section palette: changed here and in the files; the files' side is taken

The app’s side stays in the brand’s history. A push that kept edits from the app ends with The brand holds changes these files lack: artbucket brand pull brings them in.

Without a base (a folder never pulled on this machine, or --replace), a push takes the files whole, and an edit made in the app is undone. diff shows it first, as a change back to what the files say:

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

A CI job checks the folder on pull requests and pushes it from the main branch. Keep the key as a secret, with the server’s address beside it.

name: Brand
on:
pull_request:
paths: ["brand/**"]
push:
branches: [main]
paths: ["brand/**"]
env:
ARTBUCKET_URL: https://assets.example.com
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"
  • On GitLab, the image saves installing Node: image: { name: ghcr.io/pwnera/artbucket/cli:1, entrypoint: [""] }, with artbucket brand diff brand --brand acme in script.
  • 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 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.

Everything the CLI does is a few calls to the sync API, which any language can make: Sync API.