Source: https://worq3r.com/en/docs/cli [Documentation](https://worq3r.com/docs) [Open app](https://worq3r.com/login) Documentation / worqer-cli # 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 page [Install the CLI](https://worq3r.com/en/docs/cli#install-cli) [Homebrew on macOS](https://worq3r.com/en/docs/cli#homebrew) [Run CLI commands](https://worq3r.com/en/docs/cli#run-in-container) [Open the container shell](https://worq3r.com/en/docs/cli#container-shell) [Quick start](https://worq3r.com/en/docs/cli#quickstart) [Commands](https://worq3r.com/en/docs/cli#commands) [Global flags](https://worq3r.com/en/docs/cli#global-flags) [Environment overrides](https://worq3r.com/en/docs/cli#environment) [Files it writes](https://worq3r.com/en/docs/cli#files) [Troubleshooting](https://worq3r.com/en/docs/cli#cli-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 ```text 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 ```text worqer-cli login worqer-cli status worqer-cli --help worqer-cli version ``` ### Run the Docker image ```text 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 `. 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`. ```text 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 show`Profile 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 ```text 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 ```text 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. ```text brew untap iagorithm/tap brew tap iagorithm/tap brew reinstall --cask worqer-cli worqer-cli version ``` ### Uninstall ```text 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: ```text docker exec -it worqer-cli-container worqer-cli [arguments] ``` Common examples: ```text 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: ```text 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. ```text 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. ```text 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. ```text 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. ```text 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 ` Run a different worker image instead of the default cjarn/worq3r-runner. Use it to pin a tag or test a build. ```text 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 ` Use a specific Runner image instead of cjarn/worq3r-runner:latest. ```text 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 ` Use a specific Runner image for the authorization and restart. ```text worqer-cli reset-token runner ``` ### `worqer-cli claim ` 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. `` The worker's claim token. `worqer-cli install` prints it, or read it from ~/data/worker-token on the machine running the worker. ```text 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. ```text worqer-cli workers ``` ### Projects ### `worqer-cli projects` List projects in this workspace. The ALIAS column is the name every other command takes as . It is the same name the dashboard shows, so the two never disagree. ```text worqer-cli projects ``` ### `worqer-cli sync ` 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. `` 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 ` 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. ```text worqer-cli sync my-app worqer-cli sync my-app --follow worqer-cli sync my-app --worker ``` ### `worqer-cli deploy ` 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. `` 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 ` 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 ` 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. ```text 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 ``` ### `worqer-cli history ` 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. `` The project alias, as listed by `worqer-cli projects`. `--limit ` Maximum rows to show, between 1 and 200. Defaults to 20. ```text worqer-cli history my-app worqer-cli history my-app --limit 10 ``` ### `worqer-cli logs ` 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. `` The project alias, as listed by `worqer-cli projects`. ```text 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 ` Show only jobs for one project alias. `--limit ` Maximum rows to show. Defaults to 30. ```text 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. ```text 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 --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](https://worq3r.com/en/docs/cli#homebrew) . | 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`.