crawbl CLI

Before You Change Anything

These pages often point at shared systems. Confirm the cluster, namespace, and ownership boundary before running mutating commands.

The crawbl CLI handles local development, testing, builds, and Pulumi-based infrastructure operations.

The backend repo ships a repo-local launcher at ./crawbl. You do not need to install the binary globally.

cd crawbl-backend
./crawbl setup

./crawbl setup installs the pre-push hook, checks your machine, and prepares the repo-local ./crawbl launcher. On first run, ./crawbl builds bin/crawbl automatically.

Top-Level Commands

Command	Description
./crawbl setup	Check local prerequisites, create .env, and configure Snyk MCP
./crawbl dev ...	Local development commands (lint, verify, ...)
./crawbl test unit	Run Go unit tests
./crawbl test e2e	Run Godog/Cucumber e2e tests
./crawbl app build <component>	Build a component image
./crawbl app deploy <component>	Build, push, deploy, tag, and release a component
./crawbl app gc	Clean up old images from the container registry
./crawbl infra init	Initialize or select Pulumi stack
./crawbl infra plan	Preview infrastructure changes
./crawbl infra update	Apply infrastructure changes
./crawbl infra update --save-kubeconfig	Apply + save kubeconfig + wait for ArgoCD sync (first-time setup)
./crawbl infra destroy	Destroy infrastructure resources
./crawbl app sync [app]	Hard-refresh an ArgoCD application
./crawbl app sync [app] --force	Reset stuck operation + hard-refresh

Infrastructure Commands

Manage the DigitalOcean Kubernetes cluster and ArgoCD bootstrap.

./crawbl infra init
./crawbl infra plan
./crawbl infra update
./crawbl infra update --save-kubeconfig    # First-time setup: apply + kubeconfig + wait for ArgoCD
./crawbl infra destroy

Deploy Commands

Dev only

crawbl app deploy targets the dev cluster only. The CLI blocks deploys when the active kubectl context is do-fra1-crawbl-prod. Production deployments must go through GitHub CI (deploy-prod.yml).

Build, push to DOCR, update ArgoCD image tags, create a Git tag, and publish a GitHub release — all in one command. The tag is auto-calculated from conventional commits.

./crawbl app deploy platform        # Orchestrator + webhook + reaper
./crawbl app deploy auth-filter     # Envoy WASM auth filter
./crawbl app deploy agent-runtime   # Per-workspace agent runtime
./crawbl app deploy docs            # Docusaurus site → Cloudflare Pages
./crawbl app deploy website         # Marketing site → Cloudflare Pages
./crawbl app deploy all             # platform + auth-filter only

Pass --gc to automatically run registry garbage collection after a successful deploy:

./crawbl app deploy platform --gc

Registry GC Command

crawbl app gc removes old or untagged images from the DigitalOcean Container Registry to keep storage costs down.

./crawbl app gc

Run this periodically or pass --gc to any crawbl app deploy invocation to trigger it automatically after a successful push.

Build Commands

Build container images without deploying.

Platform Image

Single unified image for the orchestrator, userswarm webhook, migration job, backup, and reaper. The active component is selected via entrypoint.

./crawbl app build platform --tag dev --push

Auth Filter

Separate image for the TinyGo/WASM Envoy auth filter.

./crawbl app build auth-filter --tag dev --push

Docs

Docusaurus static site.

./crawbl app build docs --tag dev --push

Test Commands

./crawbl test unit
./crawbl test e2e

Repo-Local Workflow

Use the CLI from inside crawbl-backend:

./crawbl --help

If you want to force a rebuild of the local binary, set CRAWBL_REBUILD=1 for one command:

CRAWBL_REBUILD=1 ./crawbl --version

Pre-Push Hook

./crawbl setup installs a repo-managed pre-push hook.

That hook runs ./crawbl ci check, which does:

• a repo-local crawbl build
• ./crawbl test unit
• a linux/amd64 crawbl build to match the CI compile path

Notes

• Deployments happen locally via crawbl app deploy. CI is a validation gate only (e2e tests + release tagging).
• Agent Runtime images are built and deployed from crawbl-backend via crawbl app deploy agent-runtime.
• Environment Variables: Commands requiring credentials (like ./crawbl infra plan) must be run with environment variables sourced from .env. Use:

  set -a && source .env && set +a && ./crawbl <command>

  or alternatively:

  export $(grep -v '^#' .env | xargs) && ./crawbl <command>