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

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 SKILL.md that teaches an AI coding agent how to drive ro correctly — command map, auth/scope model, deploy-vs-session-token distinction, app config set PATCH delta semantics, global-config set-vs-patch, and the gotchas that aren't obvious from --help.

To use it in your own project (assumes Claude Code; adapt the path for other agent frameworks):

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

Or just copy .claude/skills/rodyssey-cli/SKILL.md verbatim into your project's skills directory. Once loaded, your agent will recognize ro app * / ro auth * / ro global-config * commands, suggest the right subcommand for natural-language requests, and avoid the common footguns (e.g., echoing a config get response back into config set --details and wiping data).

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.

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.