ro-cli

The Rodyssey CLI (@rodyssey/cli) — scaffolds, deploys, configures, and ships webapp projects to the rodyssey CMS.

Installation

The package installs three binaries: ro (recommended), rocli, and @rodyssey/cli (the canonical long form). Pick any.

Global install (most users)

# via Bun
bun install -g @rodyssey/cli

# via npm
npm install -g @rodyssey/cli

# verify
ro --version

Per-project (no global install)

# Run any time without installing
bunx @rodyssey/cli@latest auth login -e development
bunx @rodyssey/cli@latest app create my-app --auto
bunx @rodyssey/cli@latest app install-skills

Develop against this repo (live-edit the CLI itself)

git clone [email protected]:airconcepts/ro-cli.git
cd ro-cli
bun install
bun run build           # produces dist/cli.js with the ro/rocli shebangs

# Register your local checkout as the global `ro` / `rocli` / `@rodyssey/cli`:
bun link

# Now `ro` everywhere points at this checkout's dist/cli.js
ro --version            # prints whatever package.json says locally

# When done, unlink to restore the published version:
bun unlink              # from inside ro-cli/
bun install -g @rodyssey/cli    # reinstall the published one

If you want to keep both the published ro and a local-dev version side-by-side without re-linking constantly, add a shell alias for the dev tree:

# in ~/.zshrc or ~/.bashrc
alias rocli-dev='bun /absolute/path/to/ro-cli/src/cli.ts'

rocli-dev then runs your live TypeScript via Bun (no rebuild needed), while ro keeps pointing at the globally-installed published version. The SKILL.md recognizes both names.

Using with AI agents

The CLI ships with a rich skill (SKILL.md) that teaches an AI coding agent (Grok, Claude Code, etc.) how to drive ro correctly — full command map, auth/scope + identity model, deploy vs. deploy-token distinction, delta-PATCH semantics for app config set, global-config set-vs-patch, entity groups, asset uploads, promote/deploy workflows, headless/CI guidance, common pitfalls, and "when to suggest which command" tables.

Slash commands

Two packaged slash commands wrap the highest-stakes workflows as guided procedures. commands/ship-prod.md is canonical here; commands/ro-doctor.md is a synced mirror of the airconcepts/rody-skills repo — edit it there, not here:

• /ship-prod — guided promote-to-production: pre-flight checks (.env.production guard, session check, config drift preview), ro app promote with the right flags, then post-verify against the known empty-title pitfall.
• /ro-doctor — diagnoses auth/env/token/scope failures (ro auth me, env-file checks, symptom → fix mapping) and prints the exact fix commands, without ever echoing secrets.

Claude Code plugin users get them namespaced (/rodyssey-cli:ship-prod). ro app upgrade-template distributes both to user projects, project-local in .claude/commands/ and .cursor/commands/ (invoked as /ship-prod, /ro-doctor) — ship-prod.md copied from this repo's canonical source, ro-doctor.md copied from this repo's synced mirror of the rody-skills content.

Public / creator-tier edition

Non-staff creators (members of the cli-creators group) use the creator edition of the skill, rody-creator, canonical in the public airconcepts/rody-skills repo together with its guided commands /new-ro-app, /go-live, and /ro-doctor, plus the tier-neutral webapp-deploy skill (canonical there since the no-clone change; this repo carries a synced mirror for npm packaging). Install from there — Claude Code: /plugin marketplace add airconcepts/rody-skills then /plugin install rody-creator@rody-skills; Grok: grok plugin install https://github.com/airconcepts/rody-skills --trust; Cursor: copy skills/* + commands/*.md. It covers only the production-only, ownership-scoped surface — auth login/me/logout, the no-clone birth path (scaffold your own files, then ro app init [--school]; app create is staff-only and redirects creators there), app deploy, app config, app assets push, and the app share visibility ladder (private → family → school → public). The internal rodyssey-cli skill and /ship-prod stay staff-only in this repo; staff update via ro app upgrade-template as before.

Recommended: Install as a Grok Plugin (true packaged distribution)

This is the best way to get the skill with proper management, updates, and discoverability.

Important for private repo: Because airconcepts/ro-cli is private and the team uses SSH keys, use the full SSH URL:

# Install the plugin (includes the rodyssey-cli skill)
grok plugin install [email protected]:airconcepts/ro-cli.git --trust

(The bare shorthand airconcepts/ro-cli resolves to HTTPS and will not work without a GitHub token configured in your git credentials.)

Once installed:

• The skill is available globally across all your projects.
• It appears in grok inspect, the /skills and /plugins modals, and slash autocomplete (usually as /rodyssey-cli or the qualified plugin:rodyssey-cli form).
• Future improvements are delivered with grok plugin update rodyssey-cli (or via the Marketplace/Plugins UI).
• The plugin manifest lives at plugin.json + skills/ro-cli/SKILL.md in this repo.

You can manage it with:

grok plugin list
grok plugin update rodyssey-cli
grok plugin details rodyssey-cli

Or open the extensions UI with /plugins (or Ctrl+L).

This is the "true packaged" distribution method using the Grok plugin system (see the Plugins guide). Grok's git operations for plugins respect your normal SSH keys / agent / ~/.ssh/config exactly like git clone does.

You can also add it as a marketplace source using the SSH URL if you want it to appear in the /marketplace tab for your team.

Cursor (and Cursor with OpenAI models)

Cursor has strong native support for skills and rules.

Packaged support in this repo:

• .cursor/skills/rodyssey-cli/SKILL.md — the full skill in Cursor's preferred location.
• .cursor/rules/rodyssey-cli.md — additional focused rules for Cursor's rules system.
• .cursorrules at the project root (legacy Cursor support).

Install for Cursor users (private repo):

# Clone with SSH (your existing keys)
git clone [email protected]:airconcepts/ro-cli.git

# Global install (recommended)
mkdir -p ~/.cursor/skills
cp -r ro-cli/.cursor/skills/rodyssey-cli ~/.cursor/skills/

# Or project-local (if working inside a clone of this or a webapp template)
cp -r ro-cli/.cursor/skills/rodyssey-cli .cursor/skills/

If you have the ro CLI and are in a webapp project:

ro app upgrade-template

This now keeps the Cursor skill/rules in sync too (along with Grok and Claude locations).

When using Cursor with OpenAI models ("Codex-like" experience), the .cursor/ files and the detailed skill are automatically available to the agent.

OpenAI / Codex-powered agents (Continue, Aider, Copilot, Assistants, etc.)

OpenAI-based coding agents (whether direct OpenAI models or "Codex" experiences inside Cursor / VS Code extensions / Aider / Continue.dev) primarily rely on:

• AGENTS.md at the project root (this repo already ships a comprehensive one focused on the webapp template + GameSDK + CLI workflows).
• Detailed instruction files like this skill (the rodyssey-cli SKILL.md content works excellently when referenced or included in context).
• Project rules files (Cursor rules above help when the backend is OpenAI).

Recommended for pure OpenAI users:

• Clone the repo (SSH) and reference or paste relevant sections from skills/ro-cli/SKILL.md or AGENTS.md into your custom instructions / system prompt / Assistant.
• In tools that scan the working directory, simply work inside a checkout or symlink the key files.
• The ro app upgrade-template command (when available) is the easiest way to keep everything fresh in RO webapp projects.

The skill's rich description (with many trigger phrases like ro app *, DEPLOY_TOKEN, webapp.config.json, etc.) and the command map + pitfalls table make it highly effective across different agent backends.

Alternative: Project-embedded via template upgrade

If you prefer (or need) the skill committed inside a specific webapp project:

ro app upgrade-template

This pulls the latest skill and slash commands into:

• .agent/skills/ro-cli/SKILL.md
• .claude/skills/rodyssey-cli/SKILL.md (Claude compatibility)
• .cursor/skills/rodyssey-cli/SKILL.md (Cursor compatibility)
• .claude/commands/ + .cursor/commands/ (ship-prod.md, ro-doctor.md)

Manual / one-off install (any project)

# Grok / .agent layout
mkdir -p .agent/skills/ro-cli
curl -L https://raw.githubusercontent.com/airconcepts/ro-cli/main/skills/ro-cli/SKILL.md \
  -o .agent/skills/ro-cli/SKILL.md

# Claude Code
mkdir -p .claude/skills/rodyssey-cli
curl -L https://raw.githubusercontent.com/airconcepts/ro-cli/main/.claude/skills/rodyssey-cli/SKILL.md \
  -o .claude/skills/rodyssey-cli/SKILL.md

Copying the files directly also works. The plugin method above is strongly preferred for most users because it handles discovery, trust, and updates automatically.

The canonical sources of truth in this repo are skills/ro-cli/SKILL.md (staff CLI skill) and commands/ship-prod.md (staff slash command); commands/ro-doctor.md, skills/webapp-deploy/SKILL.md (kept at this path for npm packaging), and the creator-edition files are synced mirrors of the public airconcepts/rody-skills repo — edit them there. Packaged copies exist for each supported system (Grok skills/, .claude/skills/ + .claude/commands/, .cursor/skills/ + .cursor/commands/). The full maintenance checklist for keeping all locations, manifests, rules, and the src/upgrade-template.ts sync logic up to date lives in MAINTAINING.md.

Existing Frontend Projects

Use app init when a SPA/simple frontend project was not created from a Rodyssey template:

# one-time, if not already logged in
bunx @rodyssey/cli@latest auth login -e development

# from the existing project root
bunx @rodyssey/cli@latest app init --title "My Webapp"

app init creates the CMS webapp, writes WEBAPP_ID and DEPLOY_TOKEN to .env, installs Rodyssey agent skills, and adds missing package scripts such as deploy, deploy:staging, deploy:production, link-game-sdk, and install-ro-skills.

The ro-cli and webapp-deploy skills installed by this command are copied from the package's canonical skills/*/SKILL.md files, which are published to npm with the CLI.

To only install skills without provisioning a CMS webapp:

bunx @rodyssey/cli@latest app install-skills
# or, in npm-first projects
npx @rodyssey/cli@latest app install-skills

app deploy works for SPA/static frontend projects and fullstack Rodyssey templates. New fullstack platform deploys are enabled by the template's package.json flag rodyssey.workersPlatformDeploy: true; older fullstack projects without that flag keep using direct Wrangler deploy by default. SPA projects auto-detect the build runner (bun, pnpm, yarn, or npm) and upload dist/ by default:

bunx @rodyssey/cli@latest app deploy
bunx @rodyssey/cli@latest app deploy --build-command "npm run build" --dist-dir build
bunx @rodyssey/cli@latest app deploy --url https://already-hosted.example.com

Simple prompt for another agent:

You are working in an existing SPA/simple frontend project that was not created from the Rodyssey template.

First install Rodyssey agent skills:
  bunx @rodyssey/cli@latest app install-skills
If Bun is unavailable, use:
  npx @rodyssey/cli@latest app install-skills

Then read:
  .agent/skills/webapp-deploy/SKILL.md
  .agent/skills/ro-cli/SKILL.md
  .agent/skills/game-sdk/SKILL.md

If the project is not provisioned yet, run:
  bunx @rodyssey/cli@latest auth login -e development
  bunx @rodyssey/cli@latest app init --title "<app title>"

Build the app locally, keep SPA output in dist/ or deploy with --dist-dir <folder>, then deploy with:
  bunx @rodyssey/cli@latest app deploy

Authentication

ro auth login runs a PKCE browser flow. By default the browser opens the web-client's own consent page (/auth/cli-authorize) — the same site creators already use, offering the three webapps:* scopes — rather than a separate admin screen, and -e defaults to production (creators are production-only). Pass --staff to open the CMS console (/auth/cli-login) instead — the only door that can offer the full cms:*/lms:* scope catalog and its identity picker (act as yourself or a service account you host) — which shifts the default -e back to development (staff work there; an explicit -e still wins, so ro auth login --staff -e production gets a production staff token — -e overrides the environment shift, not the door: --staff -e production still opens the CMS console). An explicit --login-url overrides which door opens — it does not also override -e. --staff prints a reminder that the three webapps:* scopes — webapps:config in particular — must still be granted alongside whatever cms:*/lms:* scopes you pick, or ro app share / ro app config push will 403. Override which web-client host is opened with --consent-url <url> / RO_CONSENT_URL; --cms-url is unrelated and still governs token exchange and every other CLI↔CMS call. The token is persisted at ~/.rodyssey/config.json under auth.<env> along with an identity block describing who it represents.

Every command's -e default follows the same tiering. With no explicit -e (and no RO_ENV), the CLI resolves it from the stored session: a creator (public-tier) session defaults to production; a staff, legacy, or absent session defaults to development. RO_ENV overrides the resolved default; an explicit -e always wins over both. Whenever the default came from your session tier and isn't development, the CLI prints a one-line notice to stderr: ℹ️ Using [production] (from your session tier). Pass -e or set RO_ENV to override. (app promote's --from <env> is unaffected and always defaults to development.)

ro auth me -e <env> reads that local session and prints which environment + identity is active, including the resolved tier. Examples:

$ ro auth me -e development
Environment: development
CMS URL:     https://development-cms.rodyssey.ai
Logged in as: [email protected]
Tier: staff
Granted scopes: webapps:create, webapps:deploy-token:create, cms:global-config:read

$ ro auth me -e development        # after authorizing as a service account via --staff
Environment: development
CMS URL:     https://development-cms.rodyssey.ai
Logged in as service account: deploy-bot (id: sa-abc-123)
Tier: staff
Granted scopes: webapps:create, feed:post

$ ro auth me -e production         # a creator session (bare `ro auth login`)
Environment: production
CMS URL:     https://cms.rodyssey.ai
Logged in as: [email protected]
Tier: creator
Granted scopes: webapps:create, webapps:deploy-token:create, webapps:config

Add --remote to also call /api/auth/me for a freshness check.

Sessions that pre-date the identity-aware flow render as Logged in (legacy session — no identity block stored), with no Tier: line — there's no identity to derive it from. Re-running ro auth login -e <env> refreshes them.

Template Upgrade

app upgrade-template backfills additive template files that are missing from older projects. This includes the Dynamic Worker MCP sample endpoint and the shared mcp/ helper folder; existing local MCP files are left untouched. It also force-overwrites a whitelist of CLI/template-owned package.json scripts such as deploy, deploy:staging, deploy:production, and sync-widget-manifest.

Deployment Output

ro app deploy prints a post-deploy summary after the deploy succeeds:

• public Rodyssey app URL, e.g. https://development-app.rodyssey.ai/webapp/<id>
• published asset URL for SPA zip deployments
• platform Worker URL for Workers for Platforms fullstack deploys
• registered Dynamic Worker endpoint URLs
• MCP server endpoint URLs for api/mcp.ts
• cron job names, schedules, enabled state, and script files

SPA deploys register built dist/api/* and dist/cron-jobs/* scripts after the HTML zip has deployed. Fullstack projects with rodyssey.workersPlatformDeploy: true build locally, upload build/server Worker modules and build/client static assets to the RO platform's Workers for Platforms deploy API, sync the widget manifest, then register the same Dynamic Worker scripts. The platform path also maps supported Worker bindings from the built wrangler.json: D1 and KV bindings should omit resource IDs unless the user supplied real Cloudflare IDs, so the platform can provision one D1/KV resource per webapp and reuse it on later deploys. Other resource bindings must reference existing Cloudflare resources by ID/name and must not use template placeholders. Fullstack projects without that package flag keep the previous direct Wrangler path. Use --wrangler-direct to force direct Wrangler deploy even when the package flag is present.

For existing frontend projects, pass --dist-dir <dir> if the static build output is not dist, and --build-command <command> if the detected package manager build command is not right for the project.

For custom webapps hosted outside RO platform deployment, pass --url <https-url>. This registers the URL with CMS and skips local build/upload.

ro app sync-widget-manifest can also be run directly from a fullstack project after bun run build. It reads build/client/widgets.manifest.json by default, then PATCHes the CMS webapp config with details.widgetManifest.

Webapp Config

• ro app config get — fetch the current webapp config from the CMS.
• ro app config set — update webapp config fields (title, description, cover image, etc.) via delta PATCH.
• ro app config pull — write the CMS webapp config to a committed webapp.config.json.
• ro app config push — push webapp.config.json back to the CMS (diff preview + confirm; --dry-run, -y).
• ro app deploy --push-config — after deploying, push webapp.config.json if it differs from the CMS (otherwise you're prompted).

Entity groups

Manage membership of CMS entity groups (webapps, characters, scenes, stories). Requires a CLI session with the cms:entity-groups:read/cms:entity-groups:write scopes (ro auth login).

ro group list --type webapp                 # groups with id, name, description, school, item count
ro group items <group-id> --type webapp     # members of a group
ro group assign <group-id> --type webapp    # add (defaults --id to WEBAPP_ID from .env; idempotent)
ro group remove <group-id> --type webapp --id <webapp-id>

All subcommands accept --json for machine-readable output; writes accept -y and --dry-run.

Webapp assets

Upload or update R2-hosted webapp assets without a full deploy (uses DEPLOY_TOKEN from .env). Re-pushing a path overwrites it; the public URL is printed.

ro app assets push ./cover.png --dest images        # → prints public URL
ro app assets push ./public/img --dest img          # recursive

Release

Release automation lives in .github/workflows/release.yml and uses Changesets.

For a change that should publish a new CLI version:

bun run changeset

Choose patch, minor, or major, commit the generated .changeset/*.md file, and merge to main. The workflow opens or updates a release PR with the version bump and changelog. Merging that release PR publishes @rodyssey/cli to npm.

Configure npm trusted publishing for the package with:

• Organization/user: airconcepts
• Repository: ro-cli
• Workflow filename: release.yml

This repository is private, so npm provenance is disabled. If the repository becomes public later, change publishConfig.provenance and NPM_CONFIG_PROVENANCE back to true.

This project was created using bun init in bun v1.3.9. Bun is a fast all-in-one JavaScript runtime.