Ruska CLI

Command-line interface for Orchestra - AI Agent Orchestration Platform.

Install

# Install globally from npm
npm install -g @ruska/cli

# Or run directly with npx
npx @ruska/cli --help

Development Setup

# From the cli directory
npm install
npm run build
npm link  # Makes 'ruska' available globally

Usage

$ ruska --help

  CLI for Orchestra - AI Agent Orchestration Platform

  Usage
    $ ruska <command> [options]

  Commands
    auth              Configure API authentication
    assistants        List your assistants
    assistant <id>    Get assistant by ID
    chat <message>    Chat with the LLM (optionally with an assistant)
    create            Create a new assistant
    models            List available models
    version           Show CLI and API version
    health            Check API health status

  Options
    --ui              Launch interactive TUI mode

  Chat Options
    -a, --assistant   Assistant ID (optional, uses default chat if omitted)
    -t, --thread      Thread ID to continue a conversation
    -m, --message     Message (alternative to positional arg)
    --json            Output as newline-delimited JSON (auto-enabled when piped)
    --truncate <n>    Max characters for tool output (default: 500)
    --truncate-lines  Max lines for tool output (default: 10)
    --full-output     Disable truncation (show full output)

  Create Options
    --name            Assistant name (required)
    --model           Model to use (default: openai:gpt-4.1-mini)
    --description     Assistant description
    --system-prompt   System prompt for the assistant
    --tools           Comma-separated list of tools
    -i, --interactive Interactive mode for create command

  Examples
    $ ruska auth                                    # Configure API key and host
    $ ruska assistants                              # List your assistants
    $ ruska assistant abc-123                       # Get assistant details
    $ ruska chat "Hello"                           # Direct chat with default LLM
    $ ruska chat "Hello" -a <assistant-id>         # Chat with specific assistant
    $ ruska chat "Follow up" -t <thread-id>        # Continue existing thread
    $ ruska chat "Hello" -a <id> --json            # Output as NDJSON
    $ ruska chat "Query" -a <id> | jq '.type'      # Pipe to jq
    $ ruska create --name "My Agent" --model openai:gpt-4.1-mini
    $ ruska create -i                               # Interactive create mode
    $ ruska models                                  # List available models
    $ ruska --ui                                    # Launch TUI mode

Authentication

Before using the CLI, you need to configure your API key:

$ ruska auth

This will prompt you to:

1. Select your Orchestra host (Production, Development, or Custom URL)
2. Enter your API key (get this from Settings in the Orchestra web app)

Your credentials are stored in ~/.ruska/auth.json.

Commands

ruska auth

Configure API authentication. Interactive command that prompts for:

• Host selection (production/development/custom)
• API key input (masked for security)

The command validates your API key before saving.

ruska assistants

List all your assistants. Requires authentication.

$ ruska assistants

Your Assistants
eed8d8b3-3dcd-4396-afba-... Currency Agent (openai:gpt-4o)
a1b2c3d4-5678-90ab-cdef-... Research Assistant (anthropic:claude-3-5-sonnet)

Found 2 assistants

ruska assistant <id>

Get details for a specific assistant by ID. Requires authentication.

$ ruska assistant eed8d8b3-3dcd-4396-afba-...

Assistant Details
Last Update: 2024-01-15T10:30:00Z
ID: eed8d8b3-3dcd-4396-afba-...
Name: Currency Agent
Description: Converts currencies using real-time rates
Model: openai:gpt-4o
Tools: get_exchange_rate, convert_currency

ruska chat <message>

Chat with the LLM (optionally with an assistant) using streaming. Requires authentication.

Direct chat with default LLM:

$ ruska chat "Hello, how are you?"

Start a new conversation with an assistant:

$ ruska chat "Hello, how are you?" -a e5120812-3bcc-4b1e-93fb-3c1264291dfe

Continue an existing thread:

$ ruska chat "Follow up question" -t <thread-id>

JSON output mode (for scripting):

$ ruska chat "Hello" -a <assistant-id> --json
{"type":"chunk","content":"Hello"}
{"type":"chunk","content":"!"}
{"type":"done","response":{"messages":[...]}}

JSON mode is auto-enabled when output is piped:

$ ruska chat "Hello" -a <assistant-id> | jq '.type'

Options:

| Option | Description | | ------------------ | ----------------------------------------------------- | | -a, --assistant | Assistant ID (optional, uses default chat if omitted) | | -t, --thread | Thread ID to continue an existing conversation | | -m, --message | Message to send (alternative to positional arg) | | --tools | Tools for the chat session (see below for modes) | | --json | Output as newline-delimited JSON (NDJSON) | | --truncate <n> | Max characters for tool output (default: 500) | | --truncate-lines | Max lines for tool output (default: 10) | | --full-output | Disable truncation (show full output) |

Tool options:

| Value | Behavior | | --------------------- | --------------------------------------------------------------------------------------- | | (not provided) | Uses default tools: web_search, web_scrape, math_calculator, think_tool, python_sandbox | | --tools=disabled | Disables all tools | | --tools=tool1,tool2 | Uses only the specified tools |

Examples with tools:

# Chat with default tools (web search, scrape, calculator, think, python)
$ ruska chat "What's the weather in Dallas?"

# Chat without any tools
$ ruska chat "Tell me a joke" --tools=disabled

# Chat with specific tools only
$ ruska chat "Calculate 2+2" --tools=math_calculator
$ ruska chat "Search and analyze" --tools=web_search,think_tool

Exit codes:

| Code | Meaning | | ---- | --------------------- | | 0 | Success | | 1 | Network error | | 2 | Authentication failed | | 3 | Rate limited | | 4 | Timeout | | 5 | Server error |

ruska create

Create a new assistant. Can be used in non-interactive mode with flags or interactive mode with -i.

Non-interactive mode (default):

$ ruska create --name "My Agent" --model openai:gpt-4o --tools "web_search,calculator"

Assistant created successfully!
ID: abc12345-...
Name: My Agent
Model: openai:gpt-4o

Interactive mode:

$ ruska create -i

Create Assistant
Name: My Agent
Description: A helpful assistant
Model: openai:gpt-4o  # Use arrow keys to navigate, type to filter
System Prompt: You are a helpful assistant.
Tools: web_search, calculator

Assistant created successfully!

ruska models

List available models. Does not require authentication but will use your API key if configured.

$ ruska models

Available Models (https://chat.ruska.ai)
Default: openai:gpt-4.1-mini

Free Models:
 - openai:gpt-4.1-mini
 - anthropic:claude-3-haiku

All Models (15):
 - openai:gpt-4o
 - openai:gpt-4.1-mini
 - anthropic:claude-3-5-sonnet
 ...

ruska version

Show CLI and API version information.

$ ruska version

Ruska CLI v0.1.3
API: https://chat.ruska.ai

ruska health

Check API health status.

$ ruska health

API Health Check
Status: healthy

ruska --ui

Launch the interactive TUI (Terminal User Interface) mode with a full-screen interface.

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Run tests (linting + build + ava)
npm run test

# Format code
npm run format

# Run directly
node dist/cli.js --help

Deployment

Publishing @ruska/cli to NPM.

Automated (CI/CD)

Push a version tag to trigger the GitHub Actions workflow:

# 1. Bump version in package.json
./scripts/publish/version-bump.sh patch  # or minor, major, 1.2.3

# 2. Commit the version change
git add package.json
git commit -m "chore(cli): bump version to X.Y.Z"

# 3. Create and push tag (triggers CI publish)
git tag cli-vX.Y.Z
git push origin cli-vX.Y.Z

Manual Publishing

Use the manual scripts when CI/CD fails or for testing:

# 1. Pre-flight safety checks (optional but recommended)
./scripts/publish/pre-publish-check.sh

# 2. Bump version
./scripts/publish/version-bump.sh patch

# 3. Verify build output
./scripts/publish/verify-build.sh

# 4. Publish to NPM (includes all checks)
./scripts/publish/publish.sh

# Or dry-run first:
./scripts/publish/publish.sh --dry-run

Script Reference

| Script | Purpose | | ---------------------- | -------------------------------------------- | | version-bump.sh | Bump version (major/minor/patch or explicit) | | pre-publish-check.sh | Safety checks (secrets, TODOs, semver) | | verify-build.sh | Verify dist output is correct | | publish.sh | Full publish with all validations | | rollback.sh | Emergency: deprecate a bad version |

Rollback

If a published version has critical issues:

# Deprecate the problematic version
./scripts/publish/rollback.sh 1.2.3

# Or deprecate and recommend a specific version
./scripts/publish/rollback.sh 1.2.3 1.2.2

Requirements

• Node.js 18+
• NPM authentication (npm login)
• 2FA enabled for npm writes (recommended)
• NPM_TOKEN secret configured for CI

Configuration

Config is stored at ~/.ruska/auth.json:

{
	"apiKey": "otk_...",
	"host": "https://chat.ruska.ai"
}

Examples

Chat with Python Agent

Request:

ruska chat "Provide first 20 of fib using python_sandbox" \
  -a e5120812-3bcc-4b1e-93fb-3c1264291dfe \
  --json \
| jq -r '.response.messages[-1].content'

Response:

> Ledger Snapshot:
> Goal: Provide first 20 Fibonacci numbers using Python.
> Now: Completed Fibonacci sequence calculation.
> Next: None.
> Open Questions: None.

The first 20 Fibonacci numbers are:
0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233, 377, 610, 987, 1597, 2584, 4181.