Rye CLI Reference

The ./scripts/rye command is the fastest repo-local path for installing Rye, checking an instance, creating the first onboarding scope, and giving agents a portable context bundle.

It writes local connection state to .rye.env by default. Pass --env-file <path> if you want a separate config file.

Fast Install

Use local Docker when you want a fresh PostgreSQL instance:

./scripts/rye init local --fresh

Use an existing PostgreSQL 15+ database when Rye should live beside current application tables:

./scripts/rye init remote --db-url "$DATABASE_URL"

Both commands install the Rye schema and sync portable metadata for plugins, skills, capabilities, and contributed node, edge, assertion, event, and artifact types.

The older aliases still work:

./scripts/rye local --fresh
./scripts/rye remote --db-url "$DATABASE_URL"

Health and Status

Check database reachability and metadata totals:

./scripts/rye doctor
./scripts/rye doctor --json

Inspect installed node types, active scopes, plugins, and skills:

./scripts/rye status
./scripts/rye status --json

status --json returns rye_agent_context(), which is the same portable bundle agents should use to orient themselves.

Catalog Commands

List installed plugin metadata:

./scripts/rye catalog plugins
./scripts/rye catalog plugins --json

List synced Rye skill manifests:

./scripts/rye catalog skills
./scripts/rye catalog skills --json

List capabilities contributed by plugins and skills:

./scripts/rye catalog capabilities
./scripts/rye catalog capabilities --json

These commands call the portable catalog functions:

• rye_plugin_catalog()
• rye_skill_catalog()
• rye_capability_catalog()

Onboarding Scope

Create and activate the first onboarding scope:

./scripts/rye onboard create \
  --label "First Scope" \
  --purpose "Describe the limited workflow Rye should assist first."

The command records default policies for expected contexts, holding context, unexpected context handling, retention, evidence review, allowed types, and enabled plugins. It activates the scope so agents can request a compiled context bundle.

The older alias still works:

./scripts/rye onboard --label "First Scope" --purpose "..."

Agent Context

Return catalog, plugin, skill, capability, source, scope, and policy context:

./scripts/rye context
./scripts/rye context --json

Select a specific scope by UUID or scope key:

./scripts/rye context --scope first-scope --json

This calls rye_agent_context(scope_id). If exactly one scope is active, Rye selects it automatically. If multiple scopes are active, pass --scope.

Source Commands

Review known source accounts and containers:

./scripts/rye sources inventory
./scripts/rye sources inventory --json

Find source accounts and containers that still need context confirmation:

./scripts/rye sources pending-context
./scripts/rye sources pending-context --json

These commands call:

• rye_source_inventory()
• rye_pending_context_confirmations()

Global Options

Use a database without relying on .rye.env:

./scripts/rye --db-url "$DATABASE_URL" status

Use a non-default Rye schema:

./scripts/rye --schema rye status

Return JSON where supported:

./scripts/rye --json context

Use quiet mode for scripts:

./scripts/rye --quiet doctor