# workers-cli

`workers` is the command-line tool for publishing workers to the [iii worker registry](https://workers.iii.dev).
Run it in a worker project: it uploads the artifacts **you have already built**, registers a new immutable version
with its README, metadata and skills, and makes it installable by anyone running iii. It never compiles, packages or
archives anything for you.

```sh
workers login

# binary worker: a folder of pre-built <bin>-<target-triple>.tar.gz archives
workers publish --artifacts ./dist --skills ./skills

# Python or Node.js worker (bundle): one .tar.gz you built, with iii.worker.yaml at its root
workers publish --artifacts ./build/hello.tar.gz --skills ./skills
```

Publishing a Python or Node.js worker? Read [Python and Node.js workers](#python-and-nodejs-workers-bundles) first:
the archive must contain `iii.worker.yaml` and everything the worker needs at runtime.

## Install

```sh
curl -fsSL https://workers.iii.dev/install/workers-cli/latest.sh | sh
```

The installer detects your OS and CPU architecture, downloads the matching archive, verifies its SHA-256 checksum
and places the `workers` binary in `~/.local/bin`. If that directory is not on your `PATH`, it tells you how to add
it.

- **Custom location:** set `INSTALL_DIR`, e.g. `curl -fsSL … | INSTALL_DIR="$HOME/bin" sh`.
- **Pin a version:** replace `latest` with a release tag (`next`) or an exact version, e.g.
  `https://workers.iii.dev/install/workers-cli/0.1.0.sh`.

Supported platforms:

| OS | Targets |
| --- | --- |
| macOS | `aarch64-apple-darwin` (Apple Silicon), `x86_64-apple-darwin` (Intel) |
| Linux | `x86_64-unknown-linux-musl` (static, any distribution), `x86_64-unknown-linux-gnu`, `aarch64-unknown-linux-gnu`, `armv7-unknown-linux-gnueabihf` |
| Windows | `x86_64-pc-windows-msvc`, `aarch64-pc-windows-msvc` (run the installer from Git Bash, MSYS2 or Cygwin) |

Check the installation with `workers --version`. Run `workers --help` or `workers publish --help` for the built-in
reference.

### Build from source

With a stable Rust toolchain, from the CLI's source directory:

```sh
cargo install --path .    # installs `workers` into ~/.cargo/bin
```

## How it works

The registry hosts your files on its own CDN and records their SHA-256 digests. Every
`workers publish` run goes through the same steps:

1. **Reads your project.** `iii.worker.yaml` provides the worker's name, type and metadata; `README.md` becomes the
   worker's page; the version comes from `--version` or from your language manifest.
2. **Checks the artifacts** you built, and computes the SHA-256 and size of each one locally, before anything leaves
   your machine. For a binary worker these are the per-target archives found in the `--artifacts` folder; for a
   bundle, the `.tar.gz` file itself, which the CLI opens to check that iii will be able to install and start it
   (see [What `workers` checks](#what-workers-checks)). Nothing is built or archived for you.
3. **Uploads the artifacts** to the registry, which serves them from its own CDN (`cdn.iii.cloud`). Only your API
   key is needed.
4. **Publishes the version.** The registry records the name, version, release tag, README, metadata and, for each
   artifact, its URL and digest.
5. **Attaches your skills** (optional): Markdown documentation for that version, sent right after the version is
   published.

Once published, the worker appears on [workers.iii.dev](https://workers.iii.dev) and anyone can add it to their
project:

```sh
iii trigger compose::add worker=<name>
```

**Versions are immutable.** Re-running a publish is always safe: if the version already exists with identical
artifacts, the run is a no-op (`already published with identical contents`); if the artifacts differ, the CLI stops
and asks you to bump the version. A CI job that failed halfway can simply be retried.

## Authenticate

```sh
workers login
```

Prompts for your registry API key (input is hidden) and saves it to `~/.iii/workers-api-key`
(`%USERPROFILE%\.iii\workers-api-key` on Windows), with `0600` permissions on macOS and Linux.

Without a terminal (a script, `docker run` without `-t`, an agent), pipe the key in instead. `workers login` reads
the first line of stdin whenever stdin is not a terminal; `--stdin` asks for that explicitly:

```sh
printf '%s\n' "$KEY" | workers login --stdin
```

In CI, skip `login` and set `WORKERS_API_KEY` instead; it takes precedence over the saved key. The key is only
needed to talk to the registry, so `--dry-run` and `workers check` work without it.

## Prepare your worker

A typical project looks like this:

```text
my-worker/
├── iii.worker.yaml     # worker manifest
├── Cargo.toml          # or package.json / pyproject.toml, provides the version
├── README.md           # shown on the worker's registry page
├── skills/             # optional Markdown skills
│   └── SKILL.md
└── dist/               # binary/executable: the pre-built per-target archives
```

Bundles (Python and Node.js) are laid out differently: see
[Python and Node.js workers](#python-and-nodejs-workers-bundles).

### `iii.worker.yaml`

```yaml
iii: v1
name: bridge                 # worker name on the registry
language: rust
deploy: binary               # binary | bundle | executable
manifest: Cargo.toml         # file the version is read from
bin: bridge                  # artifact file name prefix (defaults to `name`)
description: Bridge two engines.
license: Apache-2.0
repo: https://github.com/acme/bridge
tags: [bridge, remote]
experimental: false
config:                      # default configuration, shown on the worker's page
  url: ws://0.0.0.0:49134
dependencies:                # other workers, by semver range or release tag
  configuration: "latest"
```

| Field | Required | Description |
| --- | --- | --- |
| `name` | yes | The worker's name on the registry. |
| `deploy` | yes | `binary`, `bundle` or `executable`; see [Artifacts](#artifacts). |
| `manifest` | no | Language manifest, next to `iii.worker.yaml`, that holds the version: `Cargo.toml`, `package.json` or `pyproject.toml`. |
| `bin` | no | Prefix of the binary artifact file names. Defaults to `name`. |
| `repo` | no | Link to the source repository. When omitted, it is derived from `--github-repo` if given. |
| `tags` | no | Search tags. When omitted, the tags already set on the registry are kept. |
| `description`, `license`, `config`, `dependencies`, `experimental` | no | Sent to the registry as-is. |
| `scripts`, `runtime`, `env`, `resources` | bundles: `scripts.start` | Not sent to the registry: iii reads them from the copy of `iii.worker.yaml` **inside** a bundle archive. See [the fields iii reads](#2-declare-the-worker-and-how-it-starts). |

### Version

The version is resolved in this order:

1. `--version X.Y.Z`;
2. the file named by `manifest:`: the `version` field of a JSON file (`package.json`), or `[package].version` /
   `[project].version` of a TOML file (`Cargo.toml`, `pyproject.toml`).

If neither is available, `publish` stops and asks for `--version`.

### Artifacts

`--artifacts` is required, and what it points to depends on `deploy`:

| `deploy` | `--artifacts` points to | What gets published |
| --- | --- | --- |
| `binary` | a folder | One archive per platform, named `<bin>-<target-triple>.tar.gz` (or `.zip`, typically for Windows). Files that don't follow this pattern are ignored. |
| `bundle` | a `.tar.gz` **file** you built, never a folder | A single archive for every platform, e.g. a Node.js or Python worker. It must hold `iii.worker.yaml` at its root plus everything the worker needs at runtime; a folder is refused, not archived. See [What goes in the archive](#what-goes-in-the-archive). |
| `executable` | a folder | Same rules as `binary`. For standalone programs, like this CLI, that users install with `curl -fsSL https://workers.iii.dev/install/<name>/latest.sh \| sh` instead of adding them to a project. |

Example `dist/` folder for a binary worker named `bridge`:

```text
dist/
├── bridge-aarch64-apple-darwin.tar.gz
├── bridge-x86_64-apple-darwin.tar.gz
├── bridge-x86_64-unknown-linux-gnu.tar.gz
└── bridge-x86_64-pc-windows-msvc.zip
```

### Skills

`--skills` points to a folder of Markdown files, read recursively (empty files are skipped). `SKILL.md` at the root
is the overview; every other file keeps its relative path under `skills/`:

| Local file | Published as |
| --- | --- |
| `skills/SKILL.md` | `SKILL.md` |
| `skills/guides/setup.md` | `skills/guides/setup.md` |

## Publish

### Where the artifacts are hosted

```sh
workers publish --artifacts ./dist --skills ./skills   # bundle: --artifacts ./build/hello.tar.gz
```

The files are always uploaded straight to the registry and served from
`https://cdn.iii.cloud/workers/<name>/<version>/<asset>`. Only your API key is needed.

- The CLI opens a release for the version, uploads each artifact to a short-lived signed URL and then publishes.
  Transient upload failures are retried automatically, and an interrupted run resumes the same release the next time.
- Nothing becomes public until the publish succeeds: the registry first checks the presence, size and digest of every
  upload.
- Binary archives keep their `<bin>-<target-triple>` names; a bundle is always published as
  `<name>-<version>.tar.gz`, whatever its local file name.
- `--github-repo` is optional; when given, it only fills the `repo` link if `iii.worker.yaml` has none.

> Older versions of `workers` could upload the artifacts to a GitHub release instead (`--hosting github`). That is no
> longer supported: `--hosting` was removed, so drop it (and `WORKERS_HOSTING`) from your scripts. A `GITHUB_TOKEN`
> or `permissions: contents: write` your workflow only had for publishing can go too.

### Release tags

By default, a version is published under the `latest` tag: it is **stable**, installed by default and matched by
semver ranges such as `^1.0.0`. Any other tag (`next`, `beta`, `rc`, …) publishes a **candidate**, which is only
installed when requested explicitly by tag or exact version; semver ranges ignore it.

```sh
workers publish --artifacts ./dist --tag next

# users opt in explicitly:
iii trigger compose::add worker=my-worker@next
```

### Preview with `--dry-run`

`--dry-run` prints the worker, version, hosting target, every artifact with its digest and size, and the exact JSON
payload that would be sent, without uploading or publishing anything and without an API key. Use it to check the
manifest, the version and the artifact names before spending a version number. For a bundle it also runs
[the archive checks](#what-workers-checks), so an archive iii could not install fails here instead of after it is
published.

```sh
workers publish --artifacts ./dist --dry-run                # binary
workers publish --artifacts ./build/hello.tar.gz --dry-run  # bundle
```

### Flags

| Flag | Env | Default | Description |
| --- | --- | --- | --- |
| `--manifest <path>` | | `iii.worker.yaml` | Worker manifest. |
| `--readme <path>` | | `README.md` | Markdown shown on the worker's page. Must exist. |
| `--skills <dir>` | | | Folder of Markdown skills. |
| `--artifacts <path>` | | **required** | Folder of pre-built archives (`binary`, `executable`) or the `.tar.gz` file you built (`bundle`, with `iii.worker.yaml` at its root). Nothing is archived for you. |
| `--github-repo <owner/repo>` | `GITHUB_REPOSITORY` | | Repository linked as the worker's `repo` when `iii.worker.yaml` has none. Metadata only. |
| `--version <x.y.z>` | | read from `manifest:` | Version to publish. |
| `--tag <tag>` | | `latest` | Release tag. Anything other than `latest` publishes a candidate. |
| `--registry <url>` | `WORKERS_REGISTRY_URL` | `https://api.workers.iii.dev` | Registry API base URL. |
| `--dry-run` | | | Print the payload; upload and publish nothing. |

## Python and Node.js workers (bundles)

Python and Node.js workers are published with `deploy: bundle`. Instead of one archive per platform, a bundle is
**a single `.tar.gz` that serves every platform**. Login, hosting, release tags and `--dry-run` work as described
above; this section covers everything that is different.

> **`workers` never builds or archives anything.** `--artifacts` must be a `.tar.gz` file you built yourself: a
> folder such as `./dist` is refused, not archived for you. The CLI only opens the archive to check it (see
> [What `workers` checks](#what-workers-checks)), then uploads it byte for byte.

### What goes in the archive

The archive **is the worker as iii installs it**. `iii trigger compose::add worker=<name>` downloads it, extracts it
into a folder and starts the worker in a sandbox, with that folder as the working directory (`/workspace`), by
running the `scripts.start` command of the `iii.worker.yaml` it finds there. Nothing from your project reaches the
sandbox unless it is inside the archive.

The archive must contain, **at its root** (not under a folder such as `dist/`):

| Entry | Required | Why |
| --- | --- | --- |
| `iii.worker.yaml` | **yes** | iii reads it from the extracted archive to know how to start the worker. Without it, the install fails with `the archive for '<name>' held no executable`. Use the same file you publish with; see [the fields iii reads](#2-declare-the-worker-and-how-it-starts). |
| The code `scripts.start` runs | **yes** | For example `dist/index.js` or `hello/__main__.py`. Paths in `scripts.start` are relative to the archive root. |
| Dependencies | **yes**, unless `scripts.install` installs them or your code is bundled into a single file | iii does not run `npm install` or `pip install` for you. For Node.js, ship the production `node_modules/`. |
| `package.json`, `pyproject.toml`, `requirements.txt`, … | when the code or `scripts.install` needs them | For example, `"type": "module"` in `package.json` changes how Node.js loads `.js` files. |

A Node.js worker named `hello`, as it should look inside `hello.tar.gz`:

```text
./
├── iii.worker.yaml      # name: hello, scripts.start: node dist/index.js
├── package.json
├── dist/
│   ├── index.js
│   └── greet.js
└── node_modules/        # production dependencies (leave out if dist/ is a single bundled file)
```

An archive of the build folder, `tar -czf hello.tar.gz dist/`, only holds `dist/index.js`, `dist/greet.js`, …: no
`iii.worker.yaml` at its root and no dependencies. iii can never install it, so `workers` refuses to publish it.

Things the archive should **not** contain: `README.md` and `skills/` (they are published separately), tests, `.git/`,
development dependencies, and anything built for your own machine, such as a Python virtualenv (`.venv/`) or
`__pycache__/` folders: they do not work inside iii's Linux sandbox.

### 1. Lay out the project

```text
hello/
├── iii.worker.yaml     # deploy: bundle + scripts.start; published AND copied into the archive
├── package.json        # or pyproject.toml; holds the version
├── README.md           # shown on the worker's registry page (not part of the archive)
├── skills/             # optional Markdown skills (not part of the archive)
├── dist/               # your build output
├── out/                # staging folder: exactly what goes in the archive
└── build/
    └── hello.tar.gz    # the bundle: --artifacts points at this file
```

### 2. Declare the worker and how it starts

The same `iii.worker.yaml` is read twice: by `workers` when you publish (name, version, metadata), and by iii,
from inside the archive, when someone installs the worker (how to start it). Keep a single file and copy it into
the archive.

Node.js:

```yaml
iii: v1
name: hello
language: node
deploy: bundle
manifest: package.json      # version read from its "version" field
description: Say hello.
license: Apache-2.0
scripts:
  install: ""               # dependencies ship in the archive: nothing to install
  start: node dist/index.js # run from the archive root
```

Python:

```yaml
iii: v1
name: hello
language: python
deploy: bundle
manifest: pyproject.toml    # version read from [project].version
description: Say hello.
license: Apache-2.0
runtime:
  base_image: docker.io/iiidev/python:latest  # required: without it the worker runs on the Node.js image
scripts:
  install: pip install -r requirements.txt    # runs once, inside the sandbox, before the first start
  start: python -m hello
```

Fields iii reads from the manifest **inside the archive** (`workers` does not send them to the registry):

| Field | Required | Description |
| --- | --- | --- |
| `name` | **yes** | Exactly the worker's name on the registry; otherwise iii refuses to install it. |
| `scripts.start` | **yes** | Shell command that starts the worker, run from the archive root. |
| `scripts.install` | no | Shell command run once, inside the sandbox, before the first start. Use it for what cannot ship in the archive, such as Python packages with native extensions. When omitted, iii prints a warning at every start; set it to `""` when the dependencies are in the archive. |
| `scripts.setup` | **not allowed** | Refused in bundles: ship the archive ready to run. |
| `runtime.base_image` | no | OCI image the sandbox runs on. Defaults to `docker.io/iiidev/node:latest`; Python workers need `docker.io/iiidev/python:latest` (or another image with Python). `language:` does **not** select the image. |
| `env` | no | Extra environment variables for the worker. `III_URL` and `III_ENGINE_URL` are reserved and ignored. |
| `resources.cpus`, `resources.memory` | no | CPUs and memory (MB) for the sandbox. Defaults: 2 and 2048; capped at 4 and 4096. |

The manifest must be a regular file (not a link) of at most 64 KiB.

- `bin:` is not used by bundles.
- Only a literal version string is read: `version` in `package.json`, `[project].version` (or `[package].version`)
  in `pyproject.toml`. Poetry's `[tool.poetry].version` and `dynamic = ["version"]` are **not** read: add a
  `[project].version` or pass `--version`.

### 3. Build the archive

Build it in your own build step: put exactly what the worker needs at runtime in a staging folder, then archive
**the folder's contents** with `-C <folder> .`, so that they land at the archive root.

Node.js:

```sh
npm ci && npm run build                 # produces dist/
rm -rf out && mkdir -p out build
cp iii.worker.yaml package.json package-lock.json out/
cp -R dist out/dist
(cd out && npm ci --omit=dev)           # production node_modules/; skip if dist/ is a single bundled file
COPYFILE_DISABLE=1 tar -czf build/hello.tar.gz -C out .
```

Python:

```sh
rm -rf out && mkdir -p out build
cp iii.worker.yaml pyproject.toml requirements.txt out/
cp -R hello out/hello                   # the package `scripts.start` runs
COPYFILE_DISABLE=1 tar -czf build/hello.tar.gz -C out .
```

If the worker folder holds nothing else, you can archive it directly instead of staging. Write the archive
**outside** the folder, so it does not end up inside itself, and exclude what only works on your machine:

```sh
# from the worker folder, the one holding iii.worker.yaml
COPYFILE_DISABLE=1 tar -czf ../hello.tar.gz --exclude .venv --exclude __pycache__ --exclude .git --exclude '*.tar.gz' .
```

Check the result before publishing: `iii.worker.yaml` must be at the root, not under a folder. `workers check
build/hello.tar.gz` runs the same checks as `publish` (see [What `workers` checks](#what-workers-checks)).

```sh
$ tar -tzf build/hello.tar.gz
./
./iii.worker.yaml
./package.json
./dist/index.js
./dist/greet.js
./node_modules/…
```

A quick smoke test is to extract it into an empty folder and run `scripts.start` from there: a file missing from the
archive shows up immediately.

```sh
mkdir -p /tmp/hello-check && tar -xzf build/hello.tar.gz -C /tmp/hello-check
cd /tmp/hello-check && node dist/index.js
```

Keep in mind:

- **`tar -czf x.tar.gz dist/` is wrong**: it archives the folder itself (every path starts with `dist/`) and leaves
  the manifest out. Archive a folder's **contents** (`-C out .`, or `.` from inside the worker folder), with
  `iii.worker.yaml` among them.
- **One archive runs everywhere iii runs**: inside a Linux sandbox, on x86_64 or arm64 depending on the machine.
  Pure JavaScript and pure Python dependencies can ship as they are; native modules built on your machine (Node.js
  `.node` addons, Python wheels with C extensions) will not load there. For Python, install them with
  `scripts.install`; for Node.js, prefer dependencies without native addons.
- `COPYFILE_DISABLE=1` stops macOS tar from adding `._*` metadata files to the archive; elsewhere it does nothing.

### What `workers` checks

Before uploading anything, and also with `--dry-run`, `workers` opens the archive and refuses it when iii would
refuse to install or start it:

- `--artifacts` must be a **file** whose name ends in **`.tar.gz`**. Folders are refused (they are never archived
  for you), and so are `.tgz` and `.zip`.
- The file must be a valid gzip-compressed tar archive.
- It must have an `iii.worker.yaml` at its root: a regular file of at most 64 KiB, in valid YAML. When the manifest is
  missing, the error says what the archive holds instead (for example, everything under `dist/`) and how to fix it.
- The manifest's `name` must be the name being published, `scripts.start` must be set, `scripts.setup` must not be,
  and `runtime.base_image`, if set, must be a valid image reference.
- A Python worker (`language: python`, or `manifest: pyproject.toml`) must set `runtime.base_image` (or the legacy
  `runtime.kind`): without it, iii runs it on the Node.js image and it exits with `python: command not found`.

It also **warns**, without refusing the archive, about what was built for or by your own machine: Python virtualenvs
(`.venv/`, or any folder holding `pyvenv.cfg`), `__pycache__/`, `.git/` and macOS metadata (`._*` AppleDouble files,
`.DS_Store`).

`workers` does **not** run `scripts.start` or check that the files and dependencies it needs are in the archive: use
the smoke test above for that.

To run these checks on an archive alone, without a README, a version or an API key, use `workers check`:

```sh
workers check build/hello.tar.gz                 # the worker name comes from ./iii.worker.yaml
workers check hello-0.3.0.tar.gz --name hello    # or give it
```

The local file name is free: the archive is always published as `<name>-<version>.tar.gz` (`hello-0.3.0.tar.gz`).

### 4. Publish

```sh
# check the archive, the name, the version and the digest first (no API key needed)
workers publish --artifacts ./build/hello.tar.gz --dry-run

# served from https://cdn.iii.cloud/workers/hello/0.3.0/hello-0.3.0.tar.gz
workers publish --artifacts ./build/hello.tar.gz --skills ./skills
```

Once published, it installs like any other worker: `iii trigger compose::add worker=hello`.
`publish` ends with the worker page's URL. Pages are cached, so the new version can take about a minute to show there;
`iii` can install it right away.


### In GitHub Actions

```yaml
- name: Build the bundle
  run: |
    npm ci && npm run build
    mkdir -p out build
    cp iii.worker.yaml package.json package-lock.json out/
    cp -R dist out/dist
    (cd out && npm ci --omit=dev)
    tar -czf build/hello.tar.gz -C out .
- name: Publish to the iii registry
  env:
    WORKERS_API_KEY: ${{ secrets.WORKERS_API_KEY }}
  run: |
    curl -fsSL https://workers.iii.dev/install/workers-cli/latest.sh | sh
    ~/.local/bin/workers publish --artifacts build/hello.tar.gz --skills skills
```

### Common bundle errors

| Message | Fix |
| --- | --- |
| `bundle workers need --artifacts to be the .tar.gz archive, and ./dist is a folder: …` | `workers` does not archive folders. Build the archive as in [step 3](#3-build-the-archive) and pass the `.tar.gz` file. |
| `./build/hello.tar.gz does not exist: bundle workers need --artifacts to be the .tar.gz archive …` | The archive was not built yet, or the path is wrong. Build it as in [step 3](#3-build-the-archive) and point at it. |
| `… is not a .tar.gz file: bundle workers need --artifacts to be the .tar.gz archive …` | `--artifacts` is a `.tgz`, a `.zip` or an uncompressed `.tar`. Build a `.tar.gz` and point at it. |
| `… is not a valid .tar.gz archive` | The file is not a gzip-compressed tar (e.g. a renamed `.zip` or an uncompressed `.tar`). Rebuild it with `tar -czf`. |
| ``… has no iii.worker.yaml at its root, so iii cannot install it: everything in it is under `dist/` …`` | The build folder was archived instead of a staging folder with the manifest. Stage as in [step 3](#3-build-the-archive) and archive with `tar -czf … -C out .`. |
| ``… it has `out/iii.worker.yaml`, but iii only reads the one at the archive root`` | The staging folder was archived as a folder (`tar -czf x.tar.gz out`). Archive its contents: `tar -czf x.tar.gz -C out .`. |
| ``iii.worker.yaml inside … is named `x`, but the worker being published is `y` …`` | The archived manifest is stale or belongs to another worker. Copy the current `iii.worker.yaml` into the staging folder. |
| ``iii.worker.yaml inside … has no `scripts.start` …`` | Add `scripts.start` to `iii.worker.yaml` (e.g. `python src/main.py` for a Python worker, `node dist/index.js` for Node.js) and rebuild the archive. |
| ``iii.worker.yaml inside … declares `scripts.setup` …`` | Remove it: ship dependencies in the archive, or install them with `scripts.install`. |
| ``iii.worker.yaml inside … describes a Python worker (`language: python`) but sets no `runtime.base_image` …`` | `language:` does not select the sandbox image. Add `runtime.base_image: docker.io/iiidev/python:latest` to `iii.worker.yaml` and rebuild the archive. |
| ``warning: … contains `.venv/`, a Python virtualenv built on this machine …`` (also `__pycache__/`, `.git/`) | Not fatal, but leave those folders out: stage the archive, or archive with `--exclude` as in [step 3](#3-build-the-archive). |
| ``warning: … contains `._x` and possibly other `._*` files, the AppleDouble metadata macOS tar adds …`` (also `.DS_Store`) | Not fatal, but leave them out: archive with `COPYFILE_DISABLE=1 tar -czf …` as in [step 3](#3-build-the-archive). |
| `iii.worker.yaml at the root of … is N bytes; iii refuses bundle manifests over 64 KiB` | Trim the manifest below 64 KiB and rebuild the archive. |
| `the archive for '<name>' held no executable` (from `iii trigger compose::add`, not from `workers`) | The published version has no `iii.worker.yaml` at its root; it was published before `workers` checked archives. Rebuild it as in [step 3](#3-build-the-archive) and publish a **new** version. |
| `CHILD_EXITED_BEFORE_REGISTRATION` with `python: command not found` (from iii, not from `workers`) | The published version has no `runtime.base_image`, so it ran on the Node.js image; it was published before `workers` checked this. Add `runtime.base_image: docker.io/iiidev/python:latest` and publish a **new** version. |
| ``no string `version` in …/pyproject.toml; pass --version`` | The version is under `[tool.poetry]` or is dynamic. Add `[project].version` or pass `--version`. |
| ``iii.worker.yaml has no `manifest:` to read the version from; pass --version`` | Add `manifest: package.json` or `manifest: pyproject.toml`. |

## GitHub Actions

GitHub Actions sets `GITHUB_REPOSITORY`, which fills the worker's `repo` link when `iii.worker.yaml` has none, so
`--github-repo` can be omitted:

```yaml
- name: Publish to the iii registry
  env:
    WORKERS_API_KEY: ${{ secrets.WORKERS_API_KEY }}
  run: |
    curl -fsSL https://workers.iii.dev/install/workers-cli/latest.sh | sh
    ~/.local/bin/workers publish --artifacts dist --skills skills   # binary worker
```

Only `WORKERS_API_KEY` is needed.
For a bundle worker, `--artifacts` must be the `.tar.gz` file, not a folder, and the job must build that archive
first; see [In GitHub Actions](#in-github-actions).

## Troubleshooting

| Message | Fix |
| --- | --- |
| ``no API key: run `workers login` or set WORKERS_API_KEY`` | Run `workers login` or export `WORKERS_API_KEY`. |
| `error: unexpected argument '--hosting' found` | `--hosting` was removed: artifacts are always hosted on the registry. Drop the flag (and `WORKERS_HOSTING`). |
| ``no `<bin>-<target-triple>.tar.gz\|.zip` files in <dir>`` | The files in `--artifacts` don't follow the naming pattern, or `bin:` doesn't match their prefix. |
| `<path> does not exist: bundle workers need --artifacts to be the .tar.gz archive …` | The archive was not built yet, or the path is wrong: build it first ([step 3](#3-build-the-archive)) and point `--artifacts` at it. |
| `bundle workers need --artifacts to be the .tar.gz archive, and <dir> is a folder …` / `<path> is not a .tar.gz file: …` | With `deploy: bundle`, point `--artifacts` at the `.tar.gz` you built: folders are never archived for you, and `.tgz`/`.zip` are refused. |
| `no API key on stdin: pipe it in …` | `workers login` found no terminal and nothing on stdin. Pipe the key (`printf '%s\n' "$KEY" \| workers login --stdin`) or, in CI, set `WORKERS_API_KEY`. |
| `Error: No such device or address (os error 6)` from `workers login` | workers-cli 0.2.1 or older, run without a terminal. Upgrade, or set `WORKERS_API_KEY` instead of logging in. |
| The worker page does not show the version just published | Pages are cached for about a minute; `iii` can install the version right away. The `Page:` line `publish` prints is where it shows up. |
| `… has no iii.worker.yaml at its root, so iii cannot install it: …` | The bundle archive is missing its manifest, usually because the build folder was archived. See [Common bundle errors](#common-bundle-errors). |
| ``deploy `x` is not supported (only binary, bundle and executable)`` | Fix `deploy:` in `iii.worker.yaml`. |
| ``iii.worker.yaml has no `manifest:` to read the version from; pass --version`` | Add `manifest:` to `iii.worker.yaml` or pass `--version`. |
| ``no string `version` in <file>; pass --version`` | Add a `version` to your language manifest or pass `--version`. |
| `… is already published with different contents; bump the version instead of overwriting` | Versions are immutable: bump the version and publish again. |

## License

Apache-2.0