uru

Full-platform uru CLI. The package installs a uru binary and uses the same registry-backed platform operations exposed through MCP and the web UI.

Do not publish a release until the registry, MCP proxy, generated docs, and staging smoke gates are all green; run it from the repo with Bun while iterating.

cd apps/cli
bun src/index.ts login
bun src/index.ts whoami --json
bun src/index.ts switch <workspace-id>

The CLI is registry-backed. Dedicated Gem/Library/Dataset/Automation commands are thin adapters over the same platform tools used by MCP and the web UI; broader workspace, prompt/persona/context, sharing, web/file, business SQL, secret/env/token operations remain exposed through the generated operation registry while dedicated UX commands continue to mature. The CLI does not reimplement Gem lifecycle sequencing client-side.

Current commands

# Link the current directory to a server-side Gem. Writes only .uru/project.json.
bun src/index.ts link --workspace <workspace-id> --path 'library/Golden Gems/My Gem.gem'

# Initialize and operate Gems through first-class Gem commands.
bun src/index.ts init 'library/Golden Gems/My Gem.gem' --file ./main.html
bun src/index.ts build 'library/Golden Gems/My Gem.gem' --dry-run --outdir ./dist/uru
bun src/index.ts deploy 'library/Golden Gems/My Gem.gem'
bun src/index.ts deploy 'library/Golden Gems/My Gem.gem' --skip-promote --no-wait
bun src/index.ts deploy 'library/Golden Gems/My Gem.gem' --prod --skip-promote --no-wait
bun src/index.ts promote <version-id> --link-id <link-id>
bun src/index.ts rollback <version-id> --link-id <link-id> --yes
bun src/index.ts status 'library/Golden Gems/My Gem.gem' --json
bun src/index.ts logs 'library/Golden Gems/My Gem.gem' --limit 100
bun src/index.ts logs 'library/Golden Gems/My Gem.gem' --follow
bun src/index.ts --output-format stream-json logs 'library/Golden Gems/My Gem.gem' --follow
bun src/index.ts open 'library/Golden Gems/My Gem.gem'
bun src/index.ts gems inspect 'library/Golden Gems/My Gem.gem'
bun src/index.ts gems validate 'library/Golden Gems/My Gem.gem'
bun src/index.ts gems build 'library/Golden Gems/My Gem.gem'
bun src/index.ts gems versions upload 'library/Golden Gems/My Gem.gem' --message "ready"
bun src/index.ts gems versions deploy <version-id> 'library/Golden Gems/My Gem.gem'
bun src/index.ts gems checks <version-id> 'library/Golden Gems/My Gem.gem'
bun src/index.ts gems checks run security 'library/Golden Gems/My Gem.gem' --deployment-id <deployment-id> --blocking --deep
bun src/index.ts gems checks run browser 'library/Golden Gems/My Gem.gem' --deployment-id <deployment-id> --blocking
bun src/index.ts gems read 'library/Golden Gems/My Gem.gem' main.html
bun src/index.ts gems write 'library/Golden Gems/My Gem.gem' main.html --file ./main.html

# Library and dataset helpers over the platform tool surface.
bun src/index.ts library ls library
bun src/index.ts library search revenue
bun src/index.ts library mkdir 'library/Golden Gems'
bun src/index.ts library read 'library/Contexts/Client Brief.md'
bun src/index.ts library write 'library/Contexts/Client Brief.md' --file ./brief.md --create
bun src/index.ts library write 'library/Prompts/Sales Email.md' --content "Draft the follow-up." --create
bun src/index.ts library patch 'library/Prompts/Sales Email.md' --stdin
bun src/index.ts library cp 'library/Notes/Brief.md' 'library/Archive/Brief.md'
bun src/index.ts library mv 'library/Notes/Draft.md' 'library/Notes/Final.md'
bun src/index.ts library rm 'library/Notes/Old.md'
bun src/index.ts library restore 'library/Notes/Old.md'
bun src/index.ts datasets query revenue_rows --limit 50 --response-format concise --json
bun src/index.ts datasets get --params-json '{"dataset_id":"revenue_rows"}'
bun src/index.ts datasets rows-upsert --params-json '{"dataset_id":"revenue_rows","rows":[{"name":"Acme"}]}'
bun src/index.ts datasets manage-create --params-json '{"title":"Revenue Rows","data_schema":{"properties":[]}}'

# Automation helpers over the platform tool surface.
bun src/index.ts automations ls --status active --view summary
bun src/index.ts automations get <automation-id>
bun src/index.ts automations create "Daily revenue digest" --status draft
bun src/index.ts automations enable <automation-id>
bun src/index.ts automations trigger <automation-id> --input-message "Run now"
bun src/index.ts automations runs ls <automation-id> --scope workspace --limit 20
bun src/index.ts automations runs tail <run-id> --level warn
bun src/index.ts automations runs cancel <run-id> --yes

# Raw platform-tool escape hatch for diagnostics and parity.
bun src/index.ts tools ls
bun src/index.ts tools schema gem_control_plane --json
bun src/index.ts tools run gem_control_plane --params-json '{"op":"inspect","path":"library/Golden Gems/My Gem.gem"}'

# Show and execute the generated operation registry.
bun src/index.ts operations ls
bun src/index.ts operations ls --family automations
bun src/index.ts operations run gem.inspect --params-json '{"path":"library/Golden Gems/My Gem.gem"}'
bun src/index.ts library search "client brief"
bun src/index.ts docs library_fs
bun src/index.ts api platform/tools/search_tools/execute -F query=gem

# MCP client config helper. Prefer a scoped API key for real installs.
bun src/index.ts mcp config --api-key "$URU_API_KEY"
bun src/index.ts mcp install --path ~/.config/claude-code/mcp.json --api-key "$URU_API_KEY"

# Local shell integration.
bun src/index.ts complete bash
bun src/index.ts complete zsh
bun src/index.ts complete fish

Gem version commands create immutable, build-backed versions through gem_control_plane op=version_upload, then deploy those version ids through op=version_deploy. Provider-internal flags such as --runtime-provider are not accepted: runtime routing is compiled server-side from the Gem contract. Non-100 rollout percentages are accepted only with --skip-promote to stage rollout intent; live promote/rollback remains fail-closed until weighted link routing is enabled.

The scaffold defaults to the production API (https://api.uruintelligence.com). Use --api-url, URU_API_BASE, or URU_API_URL to point it at staging or a local backend:

URU_API_BASE=https://api-staging.uruintelligence.com bun src/index.ts whoami --json
URU_API_BASE=http://127.0.0.1:8000 bun src/index.ts whoami --json

Auth and local state

The default login path is browser OAuth with PKCE and OS-keychain storage. Headless environments can use device login or explicit token/API-key paths:

• uru login opens browser OAuth and stores the exchanged CLI session token in the OS keychain
• uru login --device prints a device-code URL for SSH/headless environments
• uru login --token ... stores the token in OS credential storage when available: macOS Keychain, Linux secret-tool/libsecret, or Windows Credential Manager via PowerShell
• uru login --token ... --insecure-storage is the explicit plaintext fallback
• Linux token storage requires secret-tool (often installed as libsecret-tools); Windows token storage requires PowerShell access to Credential Manager. If the OS store is unavailable, login fails closed with an actionable --insecure-storage fallback message.
• interactive commands with no stored token start browser login and then retry the command without printing login success text to stdout
• --no-input disables implicit login and exits 4 when authentication is missing
• precedence: --token / --token-file / --token-stdin > URU_TOKEN > OS keychain > --insecure-storage local config
• local config: URU_CONFIG_HOME, then XDG config home, then ~/.config/uru
• config file permissions: 0600
• linked project state: .uru/project.json with {workspaceId, gemId, libraryPath}
• no credentials are written to .uru/project.json
• Gem-scoped deploy tokens for CI use uru tokens create|ls|revoke
  • uru tokens create requires --name plus exactly one lifetime flag: --expiry <duration> or --expires-at <iso timestamp>
  • created tokens default to the server-enforced gem:deploy scope
  • custom --scope/--scopes values must include gem:deploy before the token can operate Gem deploy/query/control routes
• Gem secrets use uru secrets put|ls|rm; values are write-only
• uru env pull writes a metadata-only template, never downloads remote secret values, and clamps the output file to 0600 even when overwriting an existing file
• uru env run -- <cmd> overlays local values and redacts all non-empty values from captured output

Install shape

The package name is @uru-intelligence/cli; the installed binary is still uru:

npm install -g @uru-intelligence/cli
uru login --token "$URU_TOKEN"
uru whoami --json

For one-off usage:

printf '%s' "$URU_TOKEN" | npx @uru-intelligence/cli whoami --token-stdin --json

Release validation

Before publishing, run the full local CLI gate and the staging CLI/MCP smoke with a staging-scoped token. The smoke reads credentials from env or macOS Keychain and never prints the token. To avoid putting a token in shell history, store it as uru_staging_smoke_token with security add-generic-password -a "$USER" -s uru_staging_smoke_token -w '<token>' -U.

bun --filter=@uru-intelligence/cli run ci
URU_CLI_MCP_STAGING_SMOKE_TARGET=staging \
  STAGING_AUTH_BEARER_TOKEN=... \
  STAGING_WORKSPACE_ID=<workspace-id-if-needed> \
  bun --filter=@uru-intelligence/cli run smoke:staging -- --json

The npm package remains the canonical install path. Release builds can also produce standalone Bun-compiled binaries for the planned macOS/Linux/Windows matrix:

bun --filter=@uru-intelligence/cli run build:binaries          # current platform
bun --filter=@uru-intelligence/cli run build:binaries:matrix   # planned release matrix
bun --filter=@uru-intelligence/cli run smoke:binaries          # dry-run matrix planner

The updater command is intentionally conservative: uru update prints the exact npm install -g @uru-intelligence/cli@latest command instead of self-mutating the installation. Interactive text-mode commands also perform a bounded once-per-24h npm version check and write a single stderr notice when a newer CLI is available. The notifier is disabled for JSON/streaming output, CI, NO_UPDATE_NOTIFIER, and URU_NO_UPDATE_NOTIFIER.