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:

Select your Orchestra host (Production, Development, or Custom URL)
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.

Name	Name	Last commit message	Last commit date
Latest commit History 115 Commits 115 Commits
.github	.github
.vscode	.vscode
scripts/publish	scripts/publish
source	source
.editorconfig	.editorconfig
.eslintignore	.eslintignore
.eslintrc	.eslintrc
.gitattributes	.gitattributes
.gitignore	.gitignore
.npmignore	.npmignore
.prettierignore	.prettierignore
.prettierrc	.prettierrc
LICENSE	LICENSE
README.md	README.md
package-lock.json	package-lock.json
package.json	package.json
tsconfig.json	tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

Ruska CLI

Install

Development Setup

Usage

Authentication

Commands

`ruska auth`

`ruska assistants`

`ruska assistant <id>`

`ruska chat <message>`

`ruska create`

`ruska models`

`ruska version`

`ruska health`

`ruska --ui`

Development

Deployment

Automated (CI/CD)

Manual Publishing

Script Reference

Rollback

Requirements

Configuration

Examples

About

Releases

Packages

Contributors

Languages

Search code, repositories, users, issues, pull requests...

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Ruska CLI

Install

Development Setup

Usage

Authentication

Commands

ruska auth

ruska assistants

ruska assistant <id>

ruska chat <message>

ruska create

ruska models

ruska version

ruska health

ruska --ui

Development

Deployment

Automated (CI/CD)

Manual Publishing

Script Reference

Rollback

Requirements

Configuration

Examples

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`ruska auth`

`ruska assistants`

`ruska assistant <id>`

`ruska chat <message>`

`ruska create`

`ruska models`

`ruska version`

`ruska health`

`ruska --ui`