{"id":41932085,"url":"https://github.com/ruska-ai/ruska-cli","last_synced_at":"2026-01-25T17:40:23.971Z","repository":{"id":305571699,"uuid":"1023228188","full_name":"ruska-ai/ruska-cli","owner":"ruska-ai","description":"🧙‍♂️ Ruska CLI - Server-side Agent Harness backed by Orchestra","archived":false,"fork":false,"pushed_at":"2026-01-23T05:53:41.000Z","size":742,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"development","last_synced_at":"2026-01-23T22:58:57.235Z","etag":null,"topics":["ai-agents","claude-code","codex","cursor","opencode","orchestration","sourcegraph"],"latest_commit_sha":null,"homepage":"https://ruska.ai","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ruska-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-20T19:45:28.000Z","updated_at":"2026-01-23T05:50:59.000Z","dependencies_parsed_at":"2025-07-20T22:11:51.487Z","dependency_job_id":"586b19ed-b448-45a4-b2a3-1f7e2e897ae1","html_url":"https://github.com/ruska-ai/ruska-cli","commit_stats":null,"previous_names":["enso-labs/gilfoyle","ruska-ai/shell","ruska-ai/cli"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/ruska-ai/ruska-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruska-ai%2Fruska-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruska-ai%2Fruska-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruska-ai%2Fruska-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruska-ai%2Fruska-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ruska-ai","download_url":"https://codeload.github.com/ruska-ai/ruska-cli/tar.gz/refs/heads/development","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruska-ai%2Fruska-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28756166,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-25T16:32:25.380Z","status":"ssl_error","status_checked_at":"2026-01-25T16:32:09.189Z","response_time":113,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","claude-code","codex","cursor","opencode","orchestration","sourcegraph"],"created_at":"2026-01-25T17:40:23.897Z","updated_at":"2026-01-25T17:40:23.964Z","avatar_url":"https://github.com/ruska-ai.png","language":"TypeScript","readme":"# Ruska CLI\n\nCommand-line interface for Orchestra - AI Agent Orchestration Platform.\n\n## Install\n\n```bash\n# Install globally from npm\nnpm install -g @ruska/cli\n\n# Or run directly with npx\nnpx @ruska/cli --help\n```\n\n### Development Setup\n\n```bash\n# From the cli directory\nnpm install\nnpm run build\nnpm link  # Makes 'ruska' available globally\n```\n\n## Usage\n\n```\n$ ruska --help\n\n  CLI for Orchestra - AI Agent Orchestration Platform\n\n  Usage\n    $ ruska \u003ccommand\u003e [options]\n\n  Commands\n    auth              Configure API authentication\n    assistants        List your assistants\n    assistant \u003cid\u003e    Get assistant by ID\n    chat \u003cmessage\u003e    Chat with the LLM (optionally with an assistant)\n    create            Create a new assistant\n    models            List available models\n    version           Show CLI and API version\n    health            Check API health status\n\n  Options\n    --ui              Launch interactive TUI mode\n\n  Chat Options\n    -a, --assistant   Assistant ID (optional, uses default chat if omitted)\n    -t, --thread      Thread ID to continue a conversation\n    -m, --message     Message (alternative to positional arg)\n    --json            Output as newline-delimited JSON (auto-enabled when piped)\n    --truncate \u003cn\u003e    Max characters for tool output (default: 500)\n    --truncate-lines  Max lines for tool output (default: 10)\n    --full-output     Disable truncation (show full output)\n\n  Create Options\n    --name            Assistant name (required)\n    --model           Model to use (default: openai:gpt-4.1-mini)\n    --description     Assistant description\n    --system-prompt   System prompt for the assistant\n    --tools           Comma-separated list of tools\n    -i, --interactive Interactive mode for create command\n\n  Examples\n    $ ruska auth                                    # Configure API key and host\n    $ ruska assistants                              # List your assistants\n    $ ruska assistant abc-123                       # Get assistant details\n    $ ruska chat \"Hello\"                           # Direct chat with default LLM\n    $ ruska chat \"Hello\" -a \u003cassistant-id\u003e         # Chat with specific assistant\n    $ ruska chat \"Follow up\" -t \u003cthread-id\u003e        # Continue existing thread\n    $ ruska chat \"Hello\" -a \u003cid\u003e --json            # Output as NDJSON\n    $ ruska chat \"Query\" -a \u003cid\u003e | jq '.type'      # Pipe to jq\n    $ ruska create --name \"My Agent\" --model openai:gpt-4.1-mini\n    $ ruska create -i                               # Interactive create mode\n    $ ruska models                                  # List available models\n    $ ruska --ui                                    # Launch TUI mode\n```\n\n## Authentication\n\nBefore using the CLI, you need to configure your API key:\n\n```bash\n$ ruska auth\n```\n\nThis will prompt you to:\n\n1. Select your Orchestra host (Production, Development, or Custom URL)\n2. Enter your API key (get this from Settings in the Orchestra web app)\n\nYour credentials are stored in `~/.ruska/auth.json`.\n\n## Commands\n\n### `ruska auth`\n\nConfigure API authentication. Interactive command that prompts for:\n\n- Host selection (production/development/custom)\n- API key input (masked for security)\n\nThe command validates your API key before saving.\n\n### `ruska assistants`\n\nList all your assistants. Requires authentication.\n\n```bash\n$ ruska assistants\n\nYour Assistants\need8d8b3-3dcd-4396-afba-... Currency Agent (openai:gpt-4o)\na1b2c3d4-5678-90ab-cdef-... Research Assistant (anthropic:claude-3-5-sonnet)\n\nFound 2 assistants\n```\n\n### `ruska assistant \u003cid\u003e`\n\nGet details for a specific assistant by ID. Requires authentication.\n\n```bash\n$ ruska assistant eed8d8b3-3dcd-4396-afba-...\n\nAssistant Details\nLast Update: 2024-01-15T10:30:00Z\nID: eed8d8b3-3dcd-4396-afba-...\nName: Currency Agent\nDescription: Converts currencies using real-time rates\nModel: openai:gpt-4o\nTools: get_exchange_rate, convert_currency\n```\n\n### `ruska chat \u003cmessage\u003e`\n\nChat with the LLM (optionally with an assistant) using streaming. Requires authentication.\n\n**Direct chat with default LLM:**\n\n```bash\n$ ruska chat \"Hello, how are you?\"\n```\n\n**Start a new conversation with an assistant:**\n\n```bash\n$ ruska chat \"Hello, how are you?\" -a e5120812-3bcc-4b1e-93fb-3c1264291dfe\n```\n\n**Continue an existing thread:**\n\n```bash\n$ ruska chat \"Follow up question\" -t \u003cthread-id\u003e\n```\n\n**JSON output mode (for scripting):**\n\n```bash\n$ ruska chat \"Hello\" -a \u003cassistant-id\u003e --json\n{\"type\":\"chunk\",\"content\":\"Hello\"}\n{\"type\":\"chunk\",\"content\":\"!\"}\n{\"type\":\"done\",\"response\":{\"messages\":[...]}}\n```\n\nJSON mode is auto-enabled when output is piped:\n\n```bash\n$ ruska chat \"Hello\" -a \u003cassistant-id\u003e | jq '.type'\n```\n\n**Options:**\n\n| Option             | Description                                           |\n| ------------------ | ----------------------------------------------------- |\n| `-a, --assistant`  | Assistant ID (optional, uses default chat if omitted) |\n| `-t, --thread`     | Thread ID to continue an existing conversation        |\n| `-m, --message`    | Message to send (alternative to positional arg)       |\n| `--tools`          | Tools for the chat session (see below for modes)      |\n| `--json`           | Output as newline-delimited JSON (NDJSON)             |\n| `--truncate \u003cn\u003e`   | Max characters for tool output (default: 500)         |\n| `--truncate-lines` | Max lines for tool output (default: 10)               |\n| `--full-output`    | Disable truncation (show full output)                 |\n\n**Tool options:**\n\n| Value                 | Behavior                                                                                |\n| --------------------- | --------------------------------------------------------------------------------------- |\n| (not provided)        | Uses default tools: web_search, web_scrape, math_calculator, think_tool, python_sandbox |\n| `--tools=disabled`    | Disables all tools                                                                      |\n| `--tools=tool1,tool2` | Uses only the specified tools                                                           |\n\n**Examples with tools:**\n\n```bash\n# Chat with default tools (web search, scrape, calculator, think, python)\n$ ruska chat \"What's the weather in Dallas?\"\n\n# Chat without any tools\n$ ruska chat \"Tell me a joke\" --tools=disabled\n\n# Chat with specific tools only\n$ ruska chat \"Calculate 2+2\" --tools=math_calculator\n$ ruska chat \"Search and analyze\" --tools=web_search,think_tool\n```\n\n**Exit codes:**\n\n| Code | Meaning               |\n| ---- | --------------------- |\n| 0    | Success               |\n| 1    | Network error         |\n| 2    | Authentication failed |\n| 3    | Rate limited          |\n| 4    | Timeout               |\n| 5    | Server error          |\n\n### `ruska create`\n\nCreate a new assistant. Can be used in non-interactive mode with flags or interactive mode with `-i`.\n\n**Non-interactive mode (default):**\n\n```bash\n$ ruska create --name \"My Agent\" --model openai:gpt-4o --tools \"web_search,calculator\"\n\nAssistant created successfully!\nID: abc12345-...\nName: My Agent\nModel: openai:gpt-4o\n```\n\n**Interactive mode:**\n\n```bash\n$ ruska create -i\n\nCreate Assistant\nName: My Agent\nDescription: A helpful assistant\nModel: openai:gpt-4o  # Use arrow keys to navigate, type to filter\nSystem Prompt: You are a helpful assistant.\nTools: web_search, calculator\n\nAssistant created successfully!\n```\n\n### `ruska models`\n\nList available models. Does not require authentication but will use your API key if configured.\n\n```bash\n$ ruska models\n\nAvailable Models (https://chat.ruska.ai)\nDefault: openai:gpt-4.1-mini\n\nFree Models:\n - openai:gpt-4.1-mini\n - anthropic:claude-3-haiku\n\nAll Models (15):\n - openai:gpt-4o\n - openai:gpt-4.1-mini\n - anthropic:claude-3-5-sonnet\n ...\n```\n\n### `ruska version`\n\nShow CLI and API version information.\n\n```bash\n$ ruska version\n\nRuska CLI v0.1.3\nAPI: https://chat.ruska.ai\n```\n\n### `ruska health`\n\nCheck API health status.\n\n```bash\n$ ruska health\n\nAPI Health Check\nStatus: healthy\n```\n\n### `ruska --ui`\n\nLaunch the interactive TUI (Terminal User Interface) mode with a full-screen interface.\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Build\nnpm run build\n\n# Watch mode\nnpm run dev\n\n# Run tests (linting + build + ava)\nnpm run test\n\n# Format code\nnpm run format\n\n# Run directly\nnode dist/cli.js --help\n```\n\n## Deployment\n\nPublishing `@ruska/cli` to NPM.\n\n### Automated (CI/CD)\n\nPush a version tag to trigger the GitHub Actions workflow:\n\n```bash\n# 1. Bump version in package.json\n./scripts/publish/version-bump.sh patch  # or minor, major, 1.2.3\n\n# 2. Commit the version change\ngit add package.json\ngit commit -m \"chore(cli): bump version to X.Y.Z\"\n\n# 3. Create and push tag (triggers CI publish)\ngit tag cli-vX.Y.Z\ngit push origin cli-vX.Y.Z\n```\n\n### Manual Publishing\n\nUse the manual scripts when CI/CD fails or for testing:\n\n```bash\n# 1. Pre-flight safety checks (optional but recommended)\n./scripts/publish/pre-publish-check.sh\n\n# 2. Bump version\n./scripts/publish/version-bump.sh patch\n\n# 3. Verify build output\n./scripts/publish/verify-build.sh\n\n# 4. Publish to NPM (includes all checks)\n./scripts/publish/publish.sh\n\n# Or dry-run first:\n./scripts/publish/publish.sh --dry-run\n```\n\n### Script Reference\n\n| Script                 | Purpose                                      |\n| ---------------------- | -------------------------------------------- |\n| `version-bump.sh`      | Bump version (major/minor/patch or explicit) |\n| `pre-publish-check.sh` | Safety checks (secrets, TODOs, semver)       |\n| `verify-build.sh`      | Verify dist output is correct                |\n| `publish.sh`           | Full publish with all validations            |\n| `rollback.sh`          | Emergency: deprecate a bad version           |\n\n### Rollback\n\nIf a published version has critical issues:\n\n```bash\n# Deprecate the problematic version\n./scripts/publish/rollback.sh 1.2.3\n\n# Or deprecate and recommend a specific version\n./scripts/publish/rollback.sh 1.2.3 1.2.2\n```\n\n### Requirements\n\n- Node.js 18+\n- NPM authentication (`npm login`)\n- 2FA enabled for npm writes (recommended)\n- `NPM_TOKEN` secret configured for CI\n\n## Configuration\n\nConfig is stored at `~/.ruska/auth.json`:\n\n```json\n{\n\t\"apiKey\": \"otk_...\",\n\t\"host\": \"https://chat.ruska.ai\"\n}\n```\n\n## Examples\n\n**Chat with Python Agent**\n\n_Request:_\n\n```bash\nruska chat \"Provide first 20 of fib using python_sandbox\" \\\n  -a e5120812-3bcc-4b1e-93fb-3c1264291dfe \\\n  --json \\\n| jq -r '.response.messages[-1].content'\n```\n\n_Response:_\n\n```log\n\u003e Ledger Snapshot:\n\u003e Goal: Provide first 20 Fibonacci numbers using Python.\n\u003e Now: Completed Fibonacci sequence calculation.\n\u003e Next: None.\n\u003e Open Questions: None.\n\nThe first 20 Fibonacci numbers are:\n0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233, 377, 610, 987, 1597, 2584, 4181.\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruska-ai%2Fruska-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fruska-ai%2Fruska-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruska-ai%2Fruska-cli/lists"}