Command Line Interface

OrkaJS CLI tools

The OrkaJS CLI is a powerful command-line tool that helps you scaffold new projects, run agents in development mode, and build production-ready applications. It provides a streamlined developer experience with hot-reloading, TypeScript support out of the box, and optimized builds.

Installation

Install the CLI globally to use it from anywhere in your terminal. This gives you access to the `orka` command.

# ─────────────────────────────────────────────────────────────────────────────
# Install the OrkaJS CLI globally
# This makes the 'orka' command available system-wide
# ─────────────────────────────────────────────────────────────────────────────
 
npm install -g @orka-js/cli
 
# Or with pnpm (recommended for faster installs)
pnpm add -g @orka-js/cli
 
# Verify installation - should print the version number
orka --version

Available Commands

orka init

Create a new OrkaJS project with all dependencies and boilerplate configured

orka dev

Start development server with hot-reloading and TypeScript compilation

orka run

Execute a specific agent file directly without starting a full server

orka build

Build your application for production with optimizations

orka config

Manage OrkaJS configuration (API keys, default models, etc.)

Creating a New Project

The `orka init` command scaffolds a complete OrkaJS project with best practices already configured.

# ─────────────────────────────────────────────────────────────────────────────
# Create a new OrkaJS project
# This command will:
#   1. Create a new directory with your project name
#   2. Initialize package.json with all required dependencies
#   3. Set up TypeScript configuration (tsconfig.json)
#   4. Create a basic agent template to get you started
#   5. Configure environment variables (.env.example)
# ─────────────────────────────────────────────────────────────────────────────
 
orka init my-agent-app
 
# You'll be prompted to choose:
#   - Template: basic | rag | multi-agent | full-stack
#   - LLM Provider: openai | anthropic | ollama
#   - Package manager: npm | pnpm | yarn
 
# Navigate to your new project
cd my-agent-app
 
# Install dependencies
npm install
 
# Copy environment variables and add your API keys
cp .env.example .env

Development Mode

Run your agents in development mode with automatic reloading when files change.

# ─────────────────────────────────────────────────────────────────────────────
# Start the development server
# Features:
#   - Hot-reloading: Changes are applied instantly without restart
#   - TypeScript compilation: No need to compile manually
#   - Error overlay: Errors are displayed clearly in the terminal
#   - DevTools integration: Automatic connection to OrkaJS DevTools
# ─────────────────────────────────────────────────────────────────────────────
 
orka dev
 
# With custom port (default is 3000)
orka dev --port 4000
 
# With DevTools enabled on a specific port
orka dev --devtools-port 3001
 
# Disable automatic browser opening
orka dev --no-open
 
# Example output:
# ┌─────────────────────────────────────────────────────────────┐
# │  OrkaJS Development Server                                  │
# │                                                             │
# │  Local:    http://localhost:3000                           │
# │  DevTools: http://localhost:3001                           │
# │                                                             │
# │  Ready in 1.2s                                             │
# └─────────────────────────────────────────────────────────────┘

Running a Single Agent

Execute a specific agent file for quick testing without starting a full server.

# ─────────────────────────────────────────────────────────────────────────────
# Run a specific agent file
# Useful for:
#   - Quick testing of a single agent
#   - Running one-off tasks
#   - Debugging a specific agent in isolation
# ─────────────────────────────────────────────────────────────────────────────
 
# Run an agent file directly
orka run ./src/agents/support-agent.ts
 
# Pass input to the agent via command line
orka run ./src/agents/qa-agent.ts --input "What is OrkaJS?"
 
# Run with a specific environment file
orka run ./src/agents/my-agent.ts --env .env.production
 
# Run in verbose mode to see all LLM calls and tool executions
orka run ./src/agents/my-agent.ts --verbose
 
# Example: Running a simple agent
# File: ./hello-agent.ts
# ─────────────────────────────────────────────────────────────────────────────
# import { StreamingToolAgent } from '@orka-js/agent';
# import { OpenAIAdapter } from '@orka-js/openai';
#
# const llm = new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY! });
# const agent = new StreamingToolAgent({ goal: 'Say hello' }, llm);
#
# const result = await agent.run('Hello!');
# console.log(result);
# ─────────────────────────────────────────────────────────────────────────────
 
orka run ./hello-agent.ts

Production Build

Build your application for production deployment with tree-shaking and minification.

# ─────────────────────────────────────────────────────────────────────────────
# Build for production
# This command:
#   1. Compiles TypeScript to JavaScript
#   2. Applies tree-shaking to remove unused code
#   3. Minifies the output for smaller bundle size
#   4. Generates source maps for debugging
#   5. Outputs to the 'dist' directory
# ─────────────────────────────────────────────────────────────────────────────
 
orka build
 
# Build with a specific output directory
orka build --outdir ./build
 
# Build without minification (for debugging)
orka build --no-minify
 
# Build with source maps disabled (smaller output)
orka build --no-sourcemap
 
# Build for a specific target (node version)
orka build --target node18

Configuration

The CLI can be configured via a `orka.config.ts` file at the root of your project.

orka.config.ts

// ─────────────────────────────────────────────────────────────────────────────
// orka.config.ts - Configuration file for the OrkaJS CLI
// Place this file at the root of your project
// ─────────────────────────────────────────────────────────────────────────────
 
import { defineConfig } from '@orka-js/cli';
 
export default defineConfig({
  // ─── Project Settings ──────────────────────────────────────────────────────
 
  // Entry point for your application
  entry: './src/index.ts',
 
  // Output directory for production builds
  outDir: './dist',
 
  // ─── Development Server ────────────────────────────────────────────────────
 
  dev: {
    port: 3000,              // Port for the dev server
    open: true,              // Auto-open browser on start
    devToolsPort: 3001,      // Port for DevTools UI
  },
 
  // ─── Default LLM Configuration ─────────────────────────────────────────────
 
  llm: {
    provider: 'openai',      // Default LLM provider
    model: 'gpt-4o',         // Default model to use
    temperature: 0.7,        // Default temperature
  },
 
  // ─── Build Options ─────────────────────────────────────────────────────────
 
  build: {
    minify: true,            // Minify output for production
    sourcemap: true,         // Generate source maps
    target: 'node18',        // Target Node.js version
  },
 
  // ─── Environment Variables ─────────────────────────────────────────────────
 
  env: {
    // These will be loaded from .env files automatically
    // You can also specify defaults here
    OPENAI_API_KEY: process.env.OPENAI_API_KEY,
    ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY,
  },
});

Pro Tips

Use `orka dev` during development for the best experience with hot-reloading
The `--verbose` flag is your friend when debugging agent behavior
Always run `orka build` before deploying to production
Store API keys in `.env` files, never commit them to git