# workers-cli

Publish workers to the [iii worker registry](https://workers.iii.dev).

## Install

```sh
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

```sh
workers login
```

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

## Publish

```sh
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<version>` 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/<name>/<version>/<asset>`. 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).

```sh
workers publish --hosting registry --artifacts ./dist --skills ./skills
```

With `registry` hosting, binary artifacts keep their `<bin>-<target-triple>.tar.gz|.zip` names and a bundle
archive is published as `<name>-<version>.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 `<bin>-<target-triple>.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/<version>/`.
It needs the `WORKERS_API_KEY` repository secret.