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, common pitfalls, and "when to suggest which command" tables.

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

• .agent/skills/ro-cli/SKILL.md
• .claude/skills/rodyssey-cli/SKILL.md (Claude compatibility)

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 source of truth for the CLI skill is skills/ro-cli/SKILL.md; the existing-project deploy skill lives at skills/webapp-deploy/SKILL.md. Packaged copies exist for each supported system (Grok skills/, .claude/skills/, .cursor/skills/). The skill itself now contains a section ("Maintaining the Multi-Vendor Skill Packaging") that instructs agents working inside the ro-cli repo to keep all these locations, manifests, rules, README, and the src/upgrade-template.ts sync logic up to date whenever CLI behavior changes.

See the "When to suggest which command" table and the maintenance section inside the skill for the exact responsibilities.

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 -e <env> runs a PKCE browser flow against the CMS. The consent screen lets the user authorize the CLI to act as themselves or as a service account they host, and pick which scopes to grant. The token is persisted at ~/.rodyssey/config.json under auth.<env> along with an identity block describing who the token represents.

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

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

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

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). 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.