Skip to content

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.

Authenticate with Rotifer Cloud via OAuth.

Terminal window
rotifer login [options]

Options:

FlagDescription
--provider <name>OAuth provider: github (default) or gitlab
--endpoint <url>Cloud endpoint URL (override default)

Authentication flow:

  1. Opens browser to OAuth consent page (GitHub or GitLab)
  2. User authorizes Rotifer Protocol
  3. PKCE flow exchanges code for tokens
  4. Credentials saved to ~/.rotifer/credentials.json

Example:

Terminal window
$ rotifer login
Opening browser for GitHub authentication...
Waiting for authorization...
✓ Logged in as @yourname

Clear cloud authentication credentials.

Terminal window
rotifer logout

Example:

Terminal window
$ rotifer logout
✓ Logged out successfully

Upload a gene to the Rotifer Cloud Registry.

Terminal window
rotifer publish [gene-name] [options]

Arguments:

ArgumentRequiredDescription
gene-nameYes (unless --all)Gene name to publish

Options:

FlagDescription
--description <text>Override gene description
--changelog <text>Changelog entry for this version (max 500 chars)
--skip-arenaSkip automatic Arena submission and reputation computation
--skip-securitySkip pre-publish security checks (dangerous API / IR / secrets scan)
--allPublish all valid genes in the genes/ directory

Prerequisites:

  • Must be logged in (rotifer login)
  • Gene must have a valid phenotype.json
  • Compiled WASM (gene.ir.wasm) is recommended but optional

What gets uploaded:

  • Phenotype metadata (domain, schemas, version, fidelity)
  • WASM binary (if compiled)
  • Description and author info

After publish:

  • A .cloud-manifest.json is saved in the gene directory, linking the local gene to its cloud ID
  • The gene becomes searchable and installable by others

Example:

Terminal window
$ 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-search

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.

Terminal window
rotifer unpublish <gene> [options]

Arguments:

ArgumentRequiredDescription
geneYesGene name, name@version, or a gene UUID. With a bare name, the newest version that is still published is taken down.

Options:

FlagDescription
--yesConfirm. 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:

  1. Requires rotifer login. Only the author of a version can take it down.
  2. The version disappears from search and from the public registry.
  3. Its Arena entry, invocation history and published artifact are kept, so the leaderboard and the public call record can still be recomputed.
  4. The change is written to the public visibility log (who, when, why), and your reputation is recomputed.

Example:

Terminal window
$ 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.0

Put one of your unpublished gene versions back on the public registry.

Terminal window
rotifer republish <gene> [options]

Arguments:

ArgumentRequiredDescription
geneYesGene name, name@version, or a gene UUID. With a bare name, the newest unpublished version is restored.

Options:

FlagDescription
--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:

Terminal window
$ rotifer republish my-search@0.2.0 --reason "taken down by mistake"
✓ Republished my-search@0.2.0

Search the Cloud Registry for genes by keyword, domain, or fidelity.

Terminal window
rotifer search [query] [options]

Arguments:

ArgumentRequiredDescription
queryNoSearch keywords (matches name and description)

Options:

FlagDescription
-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:

Terminal window
$ 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>

Download and install a gene from the Cloud Registry into your local project.

Terminal window
rotifer install <gene-ref> [options]

Arguments:

ArgumentRequiredDescription
gene-refYesUUID of the gene to install

Options:

FlagDescription
--forceOverwrite if gene already exists locally

What it does:

  1. Fetches gene metadata from cloud
  2. Downloads WASM binary (if available)
  3. Creates gene directory in your project’s genes/ folder
  4. Saves phenotype.json and gene.ir.wasm

Example:

Terminal window
$ 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-search

Remove a gene from your project, keeping a snapshot so it can be restored.

Terminal window
rotifer uninstall <gene-name>

Arguments:

ArgumentRequiredDescription
gene-nameYesGene 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:

Terminal window
$ rotifer uninstall hello-world
✓ Removed hello-world
ℹ Restore it with: rotifer rollback hello-world

Restore the copy of a gene that the last overwrite or uninstall replaced.

Terminal window
rotifer rollback [gene-name]

Arguments:

ArgumentRequiredDescription
gene-nameNoGene 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-server uses the same snapshot layout, so a gene replaced through the MCP server can be restored here, and the other way round.

Example:

Terminal window
$ 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.


By default, cloud commands connect to https://cloud.rotifer.dev. You can configure a custom endpoint for alternative deployments:

Via environment variable:

Terminal window
export ROTIFER_CLOUD_ENDPOINT=https://your-instance.supabase.co

Via config file (~/.rotifer/cloud.json):

{
"endpoint": "https://your-instance.supabase.co",
"anonKey": "your-anon-key"
}

Via CLI flag:

Terminal window
rotifer publish my-gene --endpoint https://your-instance.supabase.co