https://github.com/ruska-ai/ruska-cli
🧙♂️ Ruska CLI - Server-side Agent Harness backed by Orchestra
https://github.com/ruska-ai/ruska-cli
ai-agents claude-code codex cursor opencode orchestration sourcegraph
Last synced: about 24 hours ago
JSON representation
🧙♂️ Ruska CLI - Server-side Agent Harness backed by Orchestra
- Host: GitHub
- URL: https://github.com/ruska-ai/ruska-cli
- Owner: ruska-ai
- License: apache-2.0
- Created: 2025-07-20T19:45:28.000Z (6 months ago)
- Default Branch: development
- Last Pushed: 2026-01-23T05:53:41.000Z (3 days ago)
- Last Synced: 2026-01-23T22:58:57.235Z (3 days ago)
- Topics: ai-agents, claude-code, codex, cursor, opencode, orchestration, sourcegraph
- Language: TypeScript
- Homepage: https://ruska.ai
- Size: 725 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Ruska CLI
Command-line interface for Orchestra - AI Agent Orchestration Platform.
## Install
```bash
# Install globally from npm
npm install -g @ruska/cli
# Or run directly with npx
npx @ruska/cli --help
```
### Development Setup
```bash
# 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 [options]
Commands
auth Configure API authentication
assistants List your assistants
assistant Get assistant by ID
chat 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 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 # Chat with specific assistant
$ ruska chat "Follow up" -t # Continue existing thread
$ ruska chat "Hello" -a --json # Output as NDJSON
$ ruska chat "Query" -a | 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:
```bash
$ 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.
```bash
$ 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 `
Get details for a specific assistant by ID. Requires authentication.
```bash
$ 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 `
Chat with the LLM (optionally with an assistant) using streaming. Requires authentication.
**Direct chat with default LLM:**
```bash
$ ruska chat "Hello, how are you?"
```
**Start a new conversation with an assistant:**
```bash
$ ruska chat "Hello, how are you?" -a e5120812-3bcc-4b1e-93fb-3c1264291dfe
```
**Continue an existing thread:**
```bash
$ ruska chat "Follow up question" -t
```
**JSON output mode (for scripting):**
```bash
$ ruska chat "Hello" -a --json
{"type":"chunk","content":"Hello"}
{"type":"chunk","content":"!"}
{"type":"done","response":{"messages":[...]}}
```
JSON mode is auto-enabled when output is piped:
```bash
$ ruska chat "Hello" -a | 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 ` | 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:**
```bash
# 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):**
```bash
$ 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:**
```bash
$ 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.
```bash
$ 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.
```bash
$ ruska version
Ruska CLI v0.1.3
API: https://chat.ruska.ai
```
### `ruska health`
Check API health status.
```bash
$ ruska health
API Health Check
Status: healthy
```
### `ruska --ui`
Launch the interactive TUI (Terminal User Interface) mode with a full-screen interface.
## Development
```bash
# 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:
```bash
# 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:
```bash
# 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:
```bash
# 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`:
```json
{
"apiKey": "otk_...",
"host": "https://chat.ruska.ai"
}
```
## Examples
**Chat with Python Agent**
_Request:_
```bash
ruska chat "Provide first 20 of fib using python_sandbox" \
-a e5120812-3bcc-4b1e-93fb-3c1264291dfe \
--json \
| jq -r '.response.messages[-1].content'
```
_Response:_
```log
> 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.
```