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.
Install and sign in
Section titled “Install and sign in”The CLI is the artbucket package on npm, for Node 22 and later:
npx artbucket login assets.example.com --scope write # your server; http://localhost:3000 in fullnpm install -g artbucket # to keep it, rather than npx each timelogin 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.
With Docker
Section titled “With Docker”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.
docker run --rm -it -v artbucket:/config ghcr.io/pwnera/artbucket/cli login assets.example.comdocker run --rm -v artbucket:/config -v "$PWD":/work ghcr.io/pwnera/artbucket/cli brand pull brand --brand acmeOr, without the volume, pass -e ARTBUCKET_URL -e ARTBUCKET_KEY.
logincan’t open a browser from the container: open the link it prints.localhostis the container’s own: a server on your machine ishttp://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 pullwrites keep that owner, add--user "$(id -u):$(id -g)", with-e ARTBUCKET_KEYrather than the volume.
The brand a command acts on
Section titled “The brand a command acts on”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.
brand pull
Section titled “brand pull”artbucket brand pull brand --brand acme --assets wrote brand.yaml wrote rules/color.yaml wrote pages/overview.yaml wrote assets/logo.svgacme is in brandWrites 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
--forceto take the brand’s. Before the folder’s first pull, the files git holds uncommitted count as yours. - A file of
rules/orpages/the brand no longer has is removed. - A file you named
.ymlkeeps its name. --assetsgives every asset the brand points at a path underassets/, named after its filename, and downloads the ones whose bytes the folder doesn’t already hold. A folder whoseassets/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.
brand diff
Section titled “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: 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.inkA 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 firstbrand push
Section titled “brand push”artbucket brand push brand --publish --note "Bluer primary" uploaded assets/hero.jpg ~ color.primary #1f6feb -> #1a5fd0version 14, publishedTakes the brand from its files:
- Hashes every file under
assets/, checks the files, and uploads each file they point at that the library doesn’t have yet. - Writes the brand as one version of its history, so it is undone like any
other edit, or prints
nothing changed. - 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 |
What a push overwrites
Section titled “What a push overwrites”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 takenThe 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 -> #1f6febFrom CI
Section titled “From CI”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: Brandon: 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: [""] }, withartbucket brand diff brand --brand acmeinscript. ARTBUCKET_URLis your own server when you host one. On GitLab,ARTBUCKET_URLandARTBUCKET_KEYare CI/CD variables, the key masked.- With
--note, each push to main is released with its commit’s first line. Leave--noteout 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:difflists 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.
Without the CLI
Section titled “Without the CLI”Everything the CLI does is a few calls to the sync API, which any language can make: Sync API.