Skip to content
Registry

registry-cli

(alias: workers-cli)v0.1.0

Command-line tool to publish workers and kits to the iii registry (workers.iii.dev).

license: Apache-2.0clipublishregistryreleasekits
Standalone executable
Installed on the host by its install script (default ~/.local/bin, override with INSTALL_DIR). It is not a worker, so it cannot be added to a compose graph.

Install

bash
curl -fsSL https://workers.iii.dev/install/registry-cli/0.1.0.sh | sh

Downloads the binary for this machine into ~/.local/bin. Every archive is SHA-256 verified before install.

README.md
Open as markdown

workers-cli

Publish workers to the iii worker registry.

Install

curl -fsSL https://raw.githubusercontent.com/iii-hq/workers-cli/main/install.sh | sh

Installs the workers binary for your platform into ~/.local/bin. Set WORKERS_INSTALL_DIR to change the location and WORKERS_VERSION to pin a version or tag.

Login

workers login

Asks for your registry API key and saves it to ~/.iii/workers-api-key. In CI, set WORKERS_API_KEY instead.

Publish

workers publish \
  --manifest iii.worker.yaml \
  --readme README.md \
  --skills ./skills \
  --artifacts ./dist \
  --github-repo owner/repo

The registry stores URLs, not files. Where the files go is --hosting:

  • github (default): publish uploads your artifacts to the GitHub release v of --github-repo (created if missing; needs GITHUB_TOKEN or GH_TOKEN), then registers the version, then attaches the skills.
  • registry: publish opens a release on the registry, uploads each artifact to a presigned URL in the registry's storage, then publishes with that release; the files are served from https://cdn.iii.cloud/workers///. Only the API key is needed — no GitHub token and no --github-repo (it is still used, when present, to fill the repo link if iii.worker.yaml has none).
workers publish --hosting registry --artifacts ./dist --skills ./skills

With registry hosting, binary artifacts keep their -.tar.gz|.zip names and a bundle archive is published as -.tar.gz regardless of its local file name. Nothing is public until the publish succeeds: the registry verifies every upload (presence, size, digest) and only then copies the files to the CDN and records the version.

Flag
--manifest Path to iii.worker.yaml. Default iii.worker.yaml.
--readme Required markdown file, shown on the worker's page. Default README.md.
--skills Optional folder of *.md skills. SKILL.md is the overview.
--artifacts deploy: binary: a folder of pre-built -.tar.gz (or .zip on Windows), one per platform. deploy: bundle: the .tar.gz archive itself.
--hosting github (default) or registry. Also WORKERS_HOSTING.
--github-repo owner/repo hosting the release; required with --hosting github. Defaults to GITHUB_REPOSITORY, which GitHub Actions sets for you.
--version Defaults to the version in the file named by manifest: (Cargo.toml, package.json, pyproject.toml).
--tag Release tag, default latest. Any other tag publishes a candidate that semver ranges ignore.
--dry-run Print the payload; upload and publish nothing.

Release assets are immutable with either hosting: re-running a publish for a version that already exists is a no-op when the digests match (already published with identical contents) and an error when they differ. Bump the version instead.

Releasing this CLI

Bump version in Cargo.toml, then push the matching cli-v tag (git tag cli-vX.Y.Z && git push origin cli-vX.Y.Z). The CLI Release workflow builds the same eight targets the registry serves for database, and the new binary publishes itself as workers-cli with --hosting registry, so the archives are served from https://cdn.iii.cloud/workers/workers-cli//. It needs the WORKERS_API_KEY repository secret.

Search the registry

Find workers, kits and executables, or jump to a page.