worqer-cli command reference

Every command the terminal client accepts, with its arguments and options. The CLI acts as you, not as an administrator: login signs you in with your own account, and the same rules that gate the dashboard decide what you may do from there.

On this pageInstall the CLI Homebrew on macOS Run CLI commands Open the container shell Quick start Commands Global flags Environment overrides Files it writes Troubleshooting

Install the CLI

Choose the native Homebrew cask on macOS or the minimal Linux image on any host with Docker. Both are production builds of the same CLI.

BREW

Homebrew

Native macOS binary

brew install --cask iagorithm/tap/worqer-cli

Upgrade later with brew upgrade --cask worqer-cli.

OCI

Docker image

Minimal Linux container · AMD64 and ARM64

Pull cjarn/worq3r-cli:latest and bind $HOME/data so the approved session stays visible and shared with the Runner.

Use the native Homebrew CLI

worqer-cli login
worqer-cli status
worqer-cli --help
worqer-cli version

Run the Docker image

docker pull cjarn/worq3r-cli:latest
mkdir -p "$HOME/data"
docker run -d --name worqer-cli-container --restart unless-stopped \
  --user "$(id -u):$(id -g)" \
  -v "$HOME/data:/data" \
  cjarn/worq3r-cli:latest

Access it with docker exec -it worqer-cli-container worqer-cli <command>. The Alpine image contains the static CLI, Docker CLI + Compose, TLS certificates and /bin/sh, but no compiler, source tree or runtime env file.

Host Docker access

Mounting /var/run/docker.sock gives the CLI container administrative control of Docker on this host. It is required for worqer-cli install and worqer-cli update runner.

docker exec -it worqer-cli-container worqer-cli login
docker exec -it worqer-cli-container worqer-cli install
docker exec -it worqer-cli-container worqer-cli status
docker exec -it worqer-cli-container worqer-cli --help
docker exec -it worqer-cli-container worqer-cli version
docker exec -it worqer-cli-container /bin/sh

Confirm what you ended up with — worqer-cli version prints the release, compiled profile, commit and build date. Published Homebrew and Docker packages show Profile production; local binaries showProfile development.

Building from source needs one extra step

The repository still generates native binaries: option 4 uses the local development config and option 18 uses the production config. Option 17 packages that CLI in the production image.

Authentication stays with the user

Neither distribution contains a service account. Approval creates a renewable per-user Firebase Auth session, while all projects, workers, jobs and updates travel through worq3r-api.

Install and update with Homebrew

The macOS distribution is a native binary published as a Cask in the public iagorithm/tap tap. Homebrew automatically selects Apple Silicon or Intel.

Install

brew install --cask iagorithm/tap/worqer-cli
worqer-cli version
worqer-cli login

Current releases print a short-lived worqer.app activation URL. Review the machine and workspace in the browser, then press Authorize this CLI. The CLI does not open a localhost callback port.

Update

brew update
brew upgrade --cask iagorithm/tap/worqer-cli
worqer-cli version

Compare the reported version whenever Docker and Homebrew appear to behave differently. The Docker latest image and an old local Cask can otherwise execute different login implementations.

If Homebrew remains on 0.1.0

Version 0.1.0 used the retired Google callback login. Refresh the tap and reinstall the Cask to receive the current worqer.app device-confirmation flow.

brew untap iagorithm/tap
brew tap iagorithm/tap
brew reinstall --cask worqer-cli
worqer-cli version

Uninstall

brew uninstall --cask worqer-cli

# Also remove the saved CLI session
brew uninstall --cask --zap worqer-cli

Run the CLI inside the container

Keep the container running and execute each CLI operation through docker exec. Use this pattern:

docker exec -it worqer-cli-container worqer-cli <command> [arguments]

Common examples:

docker exec -it worqer-cli-container worqer-cli login
docker exec -it worqer-cli-container worqer-cli status
docker exec -it worqer-cli-container worqer-cli projects
docker exec -it worqer-cli-container worqer-cli deploy my-app --follow
docker exec -it worqer-cli-container worqer-cli version

Do not start a new temporary container for every command. The $HOME/data bind mount preserves and exposes the approved login session and unique client identity to both the CLI and Runner.

Open the container shell

Enter the minimal Alpine Linux environment of the running CLI container with:

docker exec -it worqer-cli-container /bin/sh

The shell runs as the same unprivileged user as the CLI. The persistent login session and client identity are stored under /data, which maps to $HOME/data on the host. Exit with exit or Ctrl+D.

Quick start

From an empty machine to a running deployment, in the order the commands are meant to be run.

docker exec -it worqer-cli-container worqer-cli login
# Create and sign in the runner with the direct Docker block in /docs#create-worker
docker exec -it worqer-cli-container worqer-cli claim 8f3aQ2...
docker exec -it worqer-cli-container worqer-cli workers
docker exec -it worqer-cli-container worqer-cli projects
docker exec -it worqer-cli-container worqer-cli deploy my-app
docker exec -it worqer-cli-container worqer-cli logs my-app

Every command needs a project alias, not a repository URL

sync, deploy and logs take the alias shown by worqer-cli projects — the same name the dashboard displays.

Commands

Access

`worqer-cli login`

Authorize the CLI through worqer.app.

Prints a short-lived worqer.app URL and activation code. Approve it with an operator or admin account; no browser callback or local port is needed. The saved Firebase Auth session identifies every request sent directly to worq3r-api.

worqer-cli login

`worqer-cli logout`

Sign out and remove the local session.

Deletes the stored session file. Nothing on the server changes: this only removes this machine's ability to act as you.

worqer-cli logout

`worqer-cli whoami`

Show who you are signed in as and what you may do.

Prints the account, user id, workspace and role carried by your session. Every refusal from the database traces back to one of those four values, so this is the first thing to check when a command is denied rather than failing.

worqer-cli whoami

Workers

`worqer-cli install`

Install and run worqer-runner on this machine via Docker.

Native-binary-only helper that pulls cjarn/worq3r-runner:latest and runs it with persistent data under ~/data. CLI and Runner share ~/data/firebase-session.json, so only the first one needs authorization. The minimal CLI container intentionally has no Docker client; container users start the Runner with the direct Docker command in the worker documentation.

--image <image>: Run a different worker image instead of the default cjarn/worq3r-runner. Use it to pin a tag or test a build.

worqer-cli install
worqer-cli install --image cjarn/worq3r-runner:latest

`worqer-cli update runner`

Reinstall the Runner with its most recent image.

Pulls cjarn/worq3r-runner:latest and force-recreates only the Runner container. Its saved login, claim identity, clones and persistent data remain mounted. The previous spelling, upgrade runner, remains available as an alias.

--image <image>: Use a specific Runner image instead of cjarn/worq3r-runner:latest.

worqer-cli update runner
worqer-cli update runner --image cjarn/worq3r-runner:latest

`worqer-cli reset-token runner`

Authorize a fresh Runner login token.

Opens a new confirmation in worqer.app, saves the fresh Firebase session and then recreates the Runner. It preserves the claim token, worker identity, clones and data; a failed authorization leaves the existing container untouched.

--image <image>: Use a specific Runner image for the authorization and restart.

worqer-cli reset-token runner

`worqer-cli claim <token>`

Claim a worker using its claim token.

Ties the worker to your account, so you — and nobody else, until you share it — can sync and deploy on it. Claiming writes to the worker record, which needs the operator or admin role; a viewer is refused here with an explanation rather than a bare permission error.

<token>: The worker's claim token. `worqer-cli install` prints it, or read it from ~/data/worker-token on the machine running the worker.

worqer-cli claim AbCdEfGhIjKlMnOpQrStUvWx

`worqer-cli workers`

List workers connected to this workspace.

Shows each worker you are allowed to see, with its id, status and capacity. A worker only appears once it has checked in and its access rules admit you — private workers belonging to someone else are absent, not listed as denied.

worqer-cli workers

Projects

`worqer-cli projects`

List projects in this workspace.

The ALIAS column is the name every other command takes as <project>. It is the same name the dashboard shows, so the two never disagree.

worqer-cli projects

`worqer-cli sync <project>`

Pull the latest changes for a project on its worker.

Pulls the repository to the latest commit on its configured branch. Git only: it does not rebuild the image or restart the running containers. Use deploy when the running application has to change.

<project>: The project alias, as listed by `worqer-cli projects`.

--follow: Draw a progress bar until the worker finishes, and exit non-zero if the job does not succeed.
--worker <worker-id>: Run the job on a specific worker instead of the project's default one. It takes the worker id, not the name — the id is in the WORKER column of `worqer-cli projects`, or in the dashboard.

worqer-cli sync my-app
worqer-cli sync my-app --follow
worqer-cli sync my-app --worker <worker-id>

`worqer-cli deploy <project>`

Deploy a project on its worker.

A full rebuild and restart: it pulls, builds and recreates the project's containers. Deploy is idempotent — running it again replaces the current containers rather than requiring a manual stop first. It queues the job and returns immediately unless you ask it to wait.

<project>: The project alias, as listed by `worqer-cli projects`.

--follow: Draw a progress bar until the worker finishes, then print the commit that shipped and the container log tail. Exits non-zero when the deployment does not succeed, which is what makes it usable in a script. Interrupting it stops the watching, not the deployment.
--commit <hash>: Redeploy this commit instead of the branch tip. Hashes come from `worqer-cli history`. The rollback lasts one job: the next ordinary deploy returns to the branch tip, so a project cannot be left stranded in the past.
--worker <worker-id>: Deploy to a specific worker instead of the project's default one. It takes the worker id, not the name — the id is in the WORKER column of `worqer-cli projects`, or in the dashboard.

worqer-cli deploy my-app
worqer-cli deploy my-app --follow
worqer-cli deploy my-app --commit 9f2c1ab --follow
worqer-cli deploy my-app --worker <worker-id>

`worqer-cli history <project>`

Show a project's deployment history, with the commit each one shipped.

Past deploys and builds for one project, newest first — the same view as the Historial tab in the project's settings. The commit column is what `deploy --commit` takes, so this is where a rollback starts. Syncs are left out: they pull code without rebuilding, so they never changed what was running.

<project>: The project alias, as listed by `worqer-cli projects`.

--limit <n>: Maximum rows to show, between 1 and 200. Defaults to 20.

worqer-cli history my-app
worqer-cli history my-app --limit 10

`worqer-cli logs <project>`

Show the latest logs for a project's containers.

A snapshot of whatever the worker last reported, not a live tail. Sync or deploy the project, or refresh logs from the dashboard, to pull more recent output.

<project>: The project alias, as listed by `worqer-cli projects`.

worqer-cli logs my-app

`worqer-cli deployments`

List recent deployment jobs.

Every queued, running and finished job you can see, newest first, with its action, project, worker and result.

--project <alias>: Show only jobs for one project alias.
--limit <n>: Maximum rows to show. Defaults to 30.

worqer-cli deployments
worqer-cli deployments --project my-app --limit 10

Summary

`worqer-cli status`

One-command summary of the workspace.

Workers, projects and recent jobs in a single view — the fastest way to answer whether anything is wrong before opening the dashboard.

worqer-cli status

Global flags

Accepted by the CLI itself and by every subcommand.

Flag	What it does
`--help, -h`	Help for the CLI or for any single command. `worqer-cli <command> --help` shows that command's own options.
`--version`	Print the version of the binary you are running.

Environment overrides

Never required for normal use. Every value is compiled into the binary; these variables override one of them at runtime, which is useful for pointing a development build at a different project without rebuilding it.

Variable	Overrides
`WORQER_DATA_BACKEND`	Must remain api; direct Firebase data access is rejected.
`WORQ3R_API_URL`	Point a development binary at a different worq3r-api endpoint.
`WORQ3R_API_KEY`	Override the API transport credential in a development build.
`WORQER_FIREBASE_API_KEY`	Override the compiled-in Firebase Web API key.
`WORQER_WORKSPACE_ID`	Operate on a workspace other than the compiled-in default.

Files it writes

Path	What it holds
`~/data/firebase-session.json`	The shared CLI and Runner login. The first login creates it; both reuse and refresh it.
`~/data/client-id`	The stable identity used to audit this CLI installation.
`~/data/runner`	The Compose file `install` writes, and the directory it runs from.
`~/data`	The worker's visible persistent state, including worker-token and worker-id.
`~/data/clones`	Where the worker clones your repositories on this machine.
`~/data/nginx`	Persistent .conf files for the optional Nginx service managed by this worker.

One data directory per machine

~/data holds the worker's identity. Copying it to a second machine gives two workers the same identity, and they will fight over the same record — install a fresh worker instead.

Troubleshooting

Message	What to do
Homebrew login redirects to a host instead of showing a worqer.app confirmation	Run `worqer-cli version`. If it reports `0.1.0`, run `brew update` and `brew upgrade --cask iagorithm/tap/worqer-cli`. If it remains stale, untap, tap and reinstall using the commands in Homebrew on macOS.
Permission denied on any command	Run `worqer-cli whoami`. A missing workspace means the account was never provisioned; a `viewer` role can list things but cannot claim, sync or deploy.
Your role changed but the CLI still refuses you	Claims are frozen into a token when it is minted. The CLI refreshes a stale-looking token by itself; if it persists, run `worqer-cli login` again.
`docker was not found on PATH`	`install` needs Docker and the Compose v2 plugin on this machine. Install Docker, then run it again.
The worker never appears in `workers`	Check the container is running, then re-read its token from `~/data/worker-token` and claim it again. A worker only appears once it has checked in.
`project not found` for a name you can see in the dashboard	Use the alias from `worqer-cli projects`, not the repository name or the display title.
A deploy stays queued	The target worker is offline or busy with another job for the same project. Confirm with `worqer-cli workers` and `worqer-cli deployments`.