Cloud Commands
Cloud commands enable cross-creator gene sharing via the Rotifer Cloud Registry. Genes published to the cloud can be discovered, installed, and competed against by creators worldwide.
rotifer login
Section titled “rotifer login”Authenticate with Rotifer Cloud via OAuth.
rotifer login [options]Options:
| Flag | Description |
|---|---|
--provider <name> | OAuth provider: github (default) or gitlab |
--endpoint <url> | Cloud endpoint URL (override default) |
Authentication flow:
- Opens browser to OAuth consent page (GitHub or GitLab)
- User authorizes Rotifer Protocol
- PKCE flow exchanges code for tokens
- Credentials saved to
~/.rotifer/credentials.json
Example:
$ rotifer login Opening browser for GitHub authentication... Waiting for authorization... ✓ Logged in as @yournamerotifer logout
Section titled “rotifer logout”Clear cloud authentication credentials.
rotifer logoutExample:
$ rotifer logout ✓ Logged out successfullyrotifer publish
Section titled “rotifer publish”Upload a gene to the Rotifer Cloud Registry.
rotifer publish [gene-name] [options]Arguments:
| Argument | Required | Description |
|---|---|---|
gene-name | Yes (unless --all) | Gene name to publish |
Options:
| Flag | Description |
|---|---|
--description <text> | Override gene description |
--changelog <text> | Changelog entry for this version (max 500 chars) |
--skip-arena | Skip automatic Arena submission and reputation computation |
--skip-security | Skip pre-publish security checks (dangerous API / IR / secrets scan) |
--skip-vg | Skip the V(g) safety scan and upload a skipped badge placeholder (the badge shows skipped) |
--all | Publish all valid genes in the genes/ directory |
--trust-unsigned | Let the T1 gate run an uncompiled external gene (installed from Cloud or wrapped from ClawHub) on Node.js, unsandboxed. Without it, such a gene that has a testsuite.json is blocked at the gate |
Prerequisites:
- Must be logged in (
rotifer login) - Gene must have a valid
phenotype.json - Compiled WASM (
gene.ir.wasm) is recommended but optional - An external gene (installed from Cloud or wrapped from ClawHub) with a
testsuite.jsonmust be compiled first (rotifer compile <gene>), so the T1 gate runs its suite in the sandbox. Since 0.38.0 the gate does not run it from source on Node.js unless you pass--trust-unsigned
What gets uploaded:
- Phenotype metadata (domain, schemas, version, fidelity)
- WASM binary (if compiled)
- Description and author info
After publish:
- A
.cloud-manifest.jsonis saved in the gene directory, linking the local gene to its cloud ID - The gene becomes searchable and installable by others
Example:
$ rotifer publish my-search --description "Fast web search gene" Publishing as @yourname... Uploading to cloud registry...
✓ Gene 'my-search' published to cloud!
ID: a1b2c3d4-... Creator: yourname Domain: search.web Version: 0.1.0 Fidelity: Wrapped WASM Size: 142.3KB
Others can install it: rotifer install a1b2c3d4-... Submit to cloud Arena: rotifer arena submit --cloud my-searchrotifer unpublish
Section titled “rotifer unpublish”Take one of your published gene versions off the public registry. Nothing is deleted: the version stays on record, and only whether it is published changes.
rotifer unpublish <gene> [options]Arguments:
| Argument | Required | Description |
|---|---|---|
gene | Yes | Gene name, name@version, or a gene UUID. With a bare name, the newest version that is still published is taken down. |
Options:
| Flag | Description |
|---|---|
--yes | Confirm. Without it, the command only says what it would do and changes nothing. |
--reason <text> | Why it is coming down (up to 500 characters). Recorded with the takedown. |
What it does:
- Requires
rotifer login. Only the author of a version can take it down. - The version disappears from search and from the public registry.
- Its Arena entry, invocation history and published artifact are kept, so the leaderboard and the public call record can still be recomputed.
- The change is written to the public visibility log (who, when, why), and your reputation is recomputed.
Example:
$ rotifer unpublish my-search@0.2.0⚠ About to unpublish my-search@0.2.0.ℹ It disappears from search and the public registry.ℹ Its Arena entry, invocation history and published artifact are kept.ℹ Put it back with: rotifer republish my-search@0.2.0ℹ Re-run with --yes to confirm.
$ rotifer unpublish my-search@0.2.0 --yes --reason "superseded by 0.3.0"✓ Unpublished my-search@0.2.0ℹ Undo with: rotifer republish my-search@0.2.0rotifer republish
Section titled “rotifer republish”Put one of your unpublished gene versions back on the public registry.
rotifer republish <gene> [options]Arguments:
| Argument | Required | Description |
|---|---|---|
gene | Yes | Gene name, name@version, or a gene UUID. With a bare name, the newest unpublished version is restored. |
Options:
| Flag | Description |
|---|---|
--reason <text> | Why it is going back up. Recorded with the restore. |
Only the author can republish, and only a version that is currently unpublished. The same artifact and content hash come back; nothing is rebuilt. There is no confirmation prompt.
Example:
$ rotifer republish my-search@0.2.0 --reason "taken down by mistake"✓ Republished my-search@0.2.0rotifer search
Section titled “rotifer search”Search the Cloud Registry for genes by keyword, domain, or fidelity.
rotifer search [query] [options]Arguments:
| Argument | Required | Description |
|---|---|---|
query | No | Search keywords (matches name and description) |
Options:
| Flag | Description |
|---|---|
-d, --domain <domain> | Filter by functional domain |
--fidelity <type> | Filter by Native or Wrapped |
--sort <order> | Sort: newest, popular, fitness |
--page <n> | Page number (20 results per page) |
Example:
$ rotifer search "web search" ┌──────────────────────┬──────────┬────────────┬─────────┬──────────┬───────────┐ │ Name │ Creator │ Domain │ Version │ Fidelity │ Downloads │ ├──────────────────────┼──────────┼────────────┼─────────┼──────────┼───────────┤ │ fast-web-search │ alice │ search.web │ 0.2.0 │ Native │ 142 │ │ my-web-search │ bob │ search.web │ 0.1.0 │ Wrapped │ 38 │ └──────────────────────┴──────────┴────────────┴─────────┴──────────┴───────────┘
Page 1 — 2 of 2 total Install a gene: rotifer install <gene-ref>rotifer install
Section titled “rotifer install”Download and install a gene from the Cloud Registry into your local project.
rotifer install <gene-ref> [options]Arguments:
| Argument | Required | Description |
|---|---|---|
gene-ref | Yes | UUID of the gene to install |
Options:
| Flag | Description |
|---|---|
--force | Overwrite if gene already exists locally |
What it does:
- Fetches gene metadata from cloud
- Downloads WASM binary (if available)
- Creates gene directory in your project’s
genes/folder - Saves phenotype.json and gene.ir.wasm
Example:
$ rotifer install a1b2c3d4-e5f6-7890-abcd-ef1234567890 Downloading 'fast-web-search' from cloud... ✓ Installed to genes/fast-web-search/
Domain: search.web Fidelity: Native Version: 0.2.0
Test it: rotifer test fast-web-search Submit to Arena: rotifer arena submit fast-web-searchrotifer uninstall
Section titled “rotifer uninstall”Remove a gene from your project, keeping a snapshot so it can be restored.
rotifer uninstall <gene-name>Arguments:
| Argument | Required | Description |
|---|---|---|
gene-name | Yes | Gene to remove |
What it does: moves the gene’s directory out of your project’s genes directory into .snapshots/ next to it, and records when it was replaced. Only this project is affected. The Cloud Registry is not touched; to take a gene you published off the registry, use rotifer unpublish.
Example:
$ rotifer uninstall hello-world✓ Removed hello-worldℹ Restore it with: rotifer rollback hello-worldrotifer rollback
Section titled “rotifer rollback”Restore the copy of a gene that the last overwrite or uninstall replaced.
rotifer rollback [gene-name]Arguments:
| Argument | Required | Description |
|---|---|---|
gene-name | No | Gene to restore. Omit it to list what can be rolled back. |
What it does:
- A snapshot is taken whenever a gene is overwritten (
rotifer install --force) or removed (rotifer uninstall). - Each gene keeps one snapshot. A newer overwrite or uninstall replaces the older snapshot.
- Restoring discards the current copy, puts the snapshot back, and uses the snapshot up. Rollback undoes one step, not a history.
- It works on this project only and changes nothing in the Cloud Registry.
@rotifer/mcp-serveruses the same snapshot layout, so a gene replaced through the MCP server can be restored here, and the other way round.
Example:
$ rotifer rollbackℹ Genes that can be rolled back: hello-world — replaced 2026-10-26T03:01:30.855Zℹ Restore one with: rotifer rollback <gene-name>
$ rotifer rollback hello-world✓ Restored hello-world to ./genes/hello-worldℹ The snapshot has been used up. Rollback undoes one step, not a history.With no snapshot for that gene, it stops with error E0052 and suggests running rotifer rollback with no arguments to see what can be restored.
Custom Endpoints
Section titled “Custom Endpoints”By default, cloud commands connect to https://cloud.rotifer.dev. You can configure a custom endpoint for alternative deployments:
Via environment variable:
export ROTIFER_CLOUD_ENDPOINT=https://your-instance.supabase.coVia config file (~/.rotifer/cloud.json):
{ "endpoint": "https://your-instance.supabase.co", "anonKey": "your-anon-key"}Via CLI flag:
rotifer publish my-gene --endpoint https://your-instance.supabase.co