skip to content
iii / worker
$registry / executables

registry-cli

(alias: workers-cli)v0.0.1

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

executable
iiiverified
106 installs29 in 7d0 today
install
$curl -fsSL https://workers.iii.dev/install/registry-cli/0.0.1.sh | sh
executablelicense: Apache-2.0clipublishregistryreleasekits
  • macOS: arm64
  • Linux: x64
0skillsv0.0.1version
repoiii-hq/workers-cli

exact versions are immutable; the install script pins every archive url and verifies its sha-256 before installing.

standalone executable
installed on the host by the script above (default ~/.local/bin, override with INSTALL_DIR); not a worker, so it cannot be added to a compose graph.

readme

open as markdown
README.md

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-v0.0.2 && git push origin cli-v0.0.2). 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.