catalyst-cli (Node)

Build a project on Catalyst from your machine and pull the artifact (web / APK / IPA) back — using the same API as the web UI, authenticated with a Personal Access Token (PAT).

Same package for npm and pnpm (and yarn/bun) — they all install from the npm registry.

What is Catalyst?

Catalyst is an artifact platform for modern teams: it helps you build, sign and ship reproducible artifacts such as web bundles, Android APKs, iOS IPAs, OCI images and package artifacts from one workflow. According to the product website, Catalyst focuses on reproducible builds, provenance, caching, mobile build support and a cloud-based workflow that removes the need for heavy local setup.

In practice, Catalyst is useful when you want a reliable place to produce build artifacts without depending on your own machine for every compile, signing step or deployment action.

Why this package exists

This package exists because many developers want to use Catalyst from the terminal instead of only through the web UI. A CLI is useful when you want to:

• trigger builds from your local machine or from automation,
• upload a folder and create or refresh a project in a repeatable way,
• run preflight checks before committing time to a build,
• download artifacts back locally,
• integrate Catalyst into scripts, CI pipelines or developer workflows.

The CLI is therefore a bridge between your local development environment and the Catalyst platform: it gives you the same capabilities as the web app, but in a scriptable and terminal-friendly form.

Who uses which command?

The commands are grouped by role and workflow:

• Authentication commands: login, logout, whoami for anyone who wants to connect the CLI to a Catalyst account.
• Project management commands: projects, link, status / diff, config for developers or maintainers who work on a specific project and want to keep local folders aligned with the online project.
• Build and artifact commands: check, upload, build, pull, run for developers, CI users and release engineers who want to create artifacts from source and retrieve the result.

Each command also has common variants or declensions:

• link is used once per local folder to bind it to a known online project.
• status and diff are the same workflow viewed from a local-vs-remote perspective.
• config set <key> <value> stores defaults such as target, signing mode or project id for future commands.
• build and run can be used in local mode or GitHub Actions mode depending on the target environment.
• pull can either wait for completion or simply inspect the current state with --no-watch.

Install

npm install -g catalyst-cli      # or: pnpm add -g catalyst-cli
# or run without installing:
npx catalyst-cli --help

Requires Node ≥ 18.

Configure

Create a PAT in the web UI (Settings → API keys). It looks like cat_<prefix>_<secret>.

export CATALYST_API="https://www.bcat.website/catalyst/api"   # no trailing slash
export CATALYST_TOKEN="cat_xxxxxxxx_yyyyyyyyyyyyyyyy"

(Use --api / --token to override per command.)

Commands

| Command | Purpose | Typical user / context | Main attributes / flags | |---------|---------|------------------------|--------------------------| | login | Create or refresh the local Catalyst session used by the CLI. | Any authenticated user | --no-browser, --token, --api | | logout | Remove the stored session from the local config. | Any authenticated user | --keep-token | | whoami | Show the currently authenticated user and the active API/token source. | Any authenticated user | --api, --token | | projects | List the projects available on the connected Catalyst account. | Project maintainer | --api, --token | | link | Link a local folder to an online project and write a local config file. | Developer working on a specific project | --dir, project id positional argument | | status / diff | Compare local files with the linked or selected project to find drift. | Developer / maintainer | --dir, --project-id | | artifacts | List downloadable artifacts or download one by id. | Maintainer / CI user | --project-id, --build, --download, --out | | config | Show or update the local linked-project defaults used by later commands. | Developer | show, set <key> <value> | | check | Run a preflight assessment before building to surface likely blockers. | Developer / CI | --target, --signing-mode, --project-id, --deep | | upload | Zip a folder and create or refresh a project on Catalyst. | Developer / automation | --project-id, --name, --framework, --organization | | build | Trigger a build for a project, using the linked defaults when available. | Developer / CI | --mode, --branch, --target, --signing-mode, --max-minutes | | pull | Poll a build until it finishes and download the artifact. | Developer / CI | --out, --no-watch | | run | Perform upload → build → pull in one command. | Developer / automation | All relevant upload/build/pull flags, including --out |

Notes on the main attributes used by the workflow

• catalyst.config.json is read automatically from the current folder (or parent folders) and provides defaults for projectId, target, signingMode, and maxBuildMinutes.
• upload and run use the local folder contents as the payload, plus optional metadata such as name, framework, or organization.
• build and run honor --mode, --branch, --target, --signing-mode, and --max-minutes; --mode actions is typically used for iOS/Android builds, while --mode local is used for local/server builds.
• pull waits for the build to finish unless --no-watch is provided.

Examples

# Full loop: zip ./my-app, create project "demo", build, download the artifact
catalyst run ./my-app --name demo --out ./demo-build.zip

# Refresh an existing project and rebuild an Android APK via GitHub Actions
catalyst run ./my-app --project-id 42 --mode actions --target android

# Step by step
catalyst upload ./my-app --name demo      # → project_id=42
catalyst build 42 --mode actions --target web
catalyst pull 1234 --out ./artifact.zip

--mode local produces web artifacts. For iOS/Android use --mode actions with --target ios|android.