CLI

appbuilder is a command line tool. It pulls a shop's screens, theme and custom blocks into a folder, lets you edit them, and pushes your changes back as drafts.

Status: built. The CLI runs from the repository with the installed tsx tool. A packaged build is not yet set up.

Set up#

appbuilder login --api-url https://<your-api-address>

You are asked for an API key. The key is stored in ~/.appbuilder/config.json, which is readable only by you. You can also set the environment variables APPBUILDER_API_URL and APPBUILDER_API_KEY instead.

The API address must be https. Plain http is allowed only for localhost. The CLI never prints the key.

Commands#

Command	What it does
`login`	Save the API address and key.
`logout`	Remove the saved key.
`whoami`	Show the shop and the key's scopes.
`pull`	Download screens, theme and custom blocks into `screens/`, `theme/` and `blocks/`. Records what it pulled in `.appbuilder/state.json`.
`push`	Send only the files you changed. Custom blocks go first.
`validate`	Check custom blocks on your machine. Check screens and theme on the server.
`blocks list`	List the built-in and custom block types.
`preview`	Make a preview link and a QR code.
`publish`	Publish all drafts.

Useful flags#

--json: machine-readable output on every command.
--dry-run on push: show what would change, send nothing.
--create on push: create a new screen.
--force on pull: overwrite local edits. Without it, pull stops if a file has changed locally.
--yes on publish: skip the confirmation. Without it, you type the shop domain. A non-interactive run without --yes stops.

Things to know#

push never publishes. Only publish does.
If the server has a newer draft than you pulled, push fails and asks you to pull again.
A changed custom block needs a higher version before it pushes.
Exit codes: 0 ok, 1 failed or invalid, 2 wrong usage.

Typical loop#

appbuilder pull
# edit files in screens/, theme/ or blocks/
appbuilder validate
appbuilder push --dry-run
appbuilder push
appbuilder preview
appbuilder publish