Guide
API
Examples
Guide
API
Examples

CLI Commands

Complete reference for all Tarko Agent CLI commands and their options.

tarko / tarko run

Launches interactive Web UI for real-time conversation and file browsing.

Basic Usage

# Start interactive Web UI (default)
tarko

# Equivalent explicit command
tarko run

# Run with specific agent
tarko run ./my-agent.js

# Run with built-in agents
tarko run agent-tars
tarko run omni-tars
tarko run mcp-agent

Options

# Custom port and auto-open browser
tarko run --port 8888 --open

# Development mode with hot reload
tarko run --dev

# Debug mode with verbose logging
tarko run --debug

# Custom configuration file
tarko run --config ./custom-config.ts

# Custom workspace
tarko run --workspace ./my-workspace

Headless Mode

Silent mode execution with stdout output, perfect for scripting:

# Direct input with text output (default)
tarko run --headless --input "Analyze current directory structure"

# Pipeline input
echo "Summarize this code" | tarko run --headless

# JSON output for programmatic use
tarko run --headless --input "Analyze files" --format json

# Include debug logs in output
tarko run --headless --input "Analyze files" --include-logs

# Disable cache for fresh execution
tarko run --headless --input "Analyze files" --use-cache false

# Combine with built-in agents
tarko run agent-tars --headless --input "List directory contents"

Headless Options

OptionDescriptionDefault
--input <text>Direct input text-
--format <type>Output format: text, jsontext
--include-logsInclude debug logs in outputfalse
--use-cache <bool>Enable/disable cachingtrue

tarko serve

Starts headless API server for system integration and production deployment.

Basic Usage

# Start headless server
tarko serve

# Start server with specific agent
tarko serve ./my-agent

# Start server with built-in agent
tarko serve omni-tars

# Custom port and configuration
tarko serve --port 8888 --config ./production.config.ts

Options

# Custom port (default: 3000)
tarko serve --port 8888

# Custom host (default: 127.0.0.1)
tarko serve --host 0.0.0.0

# Access token, required once the server is reachable from other machines
tarko serve --host 0.0.0.0 --auth-token <token>

# Debug mode
tarko serve --debug

# Custom configuration
tarko serve --config ./server.config.yaml

# Custom workspace
tarko serve --workspace ./server-workspace

Remote access

tarko serve binds 127.0.0.1 by default. Once it binds an address other machines can reach, such as 0.0.0.0, every API request needs an access token, sent as Authorization: Bearer <token>. If none is set, a random token is generated and printed at startup. To keep the same token across restarts, set TARKO_AUTH_TOKEN or pass --auth-token (at least 16 characters).

When clients reach the server through a hostname or browser origin other than localhost and 127.0.0.1, for example behind a reverse proxy, allow them explicitly:

Environment variableDescription
TARKO_AUTH_TOKENAccess token, same as --auth-token
TARKO_ALLOWED_HOSTSComma-separated hostnames the server answers on, besides localhost and IP addresses on the server port. An entry without a port matches any port. Other hostnames get 403 Invalid Host header
TARKO_ALLOWED_ORIGINSComma-separated origins (scheme://host[:port]) allowed to call the API from a browser, besides http://localhost:<port> and http://127.0.0.1:<port>

API Endpoints

When running tarko serve, the following endpoints are available:

  • GET /api/v1/health - Health check
  • GET /api/v1/status - Detailed status
  • POST /api/v1/chat - Chat with agent
  • GET /api/v1/events - Event stream (WebSocket)
  • GET /metrics - Prometheus metrics (if enabled)

tarko request

Direct LLM requests for debugging and testing purposes.

Basic Usage

# Basic request
tarko request --provider openai --model gpt-4 --body '{"messages":[{"role":"user","content":"Hello"}]}'

# Load request from file
tarko request --provider openai --model gpt-4 --body ./request.json

Advanced Options

# Custom API configuration
tarko request --provider openai --model gpt-4 \
  --apiKey sk-xxx \
  --baseURL https://api.openai.com/v1 \
  --body request.json

# Streaming mode
tarko request --provider openai --model gpt-4 --body request.json --stream

# Reasoning mode (for supported models like o1)
tarko request --provider openai --model o1-preview --body request.json --thinking

# Semantic output format
tarko request --provider openai --model gpt-4 --body request.json --format semantic

Supported Providers

  • openai - OpenAI GPT models
  • anthropic - Anthropic Claude models
  • azure - Azure OpenAI Service
  • ollama - Local Ollama models
  • gemini - Google Gemini models

Request Body Format

{
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"}
  ],
  "temperature": 0.7,
  "max_tokens": 1000
}

tarko workspace

Workspace management utilities for organizing agent projects.

Commands

# Initialize new workspace in current directory
tarko workspace --init

# Open workspace in VSCode
tarko workspace --open

# Enable global workspace
tarko workspace --enable

# Disable global workspace
tarko workspace --disable

# Show workspace status and configuration
tarko workspace --status

Workspace Structure

Initializing a workspace creates:

my-workspace/
├── tarko.config.ts          # Main configuration
├── agents/                   # Custom agents
├── tools/                    # Custom tools
├── data/                     # Agent data and cache
├── logs/                     # Execution logs
└── .tarko/                   # Internal workspace data

Global Options

These options work with all commands:

Configuration

# Model configuration
tarko --model.provider openai --model.id gpt-4 --model.apiKey sk-xxx

# Custom configuration file
tarko --config ./custom.config.ts

# Custom workspace
tarko --workspace ./my-workspace

Debugging

# Enable debug logging
tarko --debug

# Verbose output
tarko --verbose

# Dry run (show what would be executed)
tarko --dry-run

# Show configuration and exit
tarko --show-config

Tool and MCP Filtering

# Include specific tools
tarko --tool.include "file_*,web_*"

# Exclude specific tools
tarko --tool.exclude "dangerous_*"

# Include specific MCP servers
tarko --mcpServer.include "filesystem,browser"

# Exclude specific MCP servers
tarko --mcpServer.exclude "experimental_*"

Environment Variables

Alternative to CLI options:

# Model configuration
export OPENAI_API_KEY=your-api-key
export ANTHROPIC_API_KEY=your-api-key

# Server configuration
export TARKO_PORT=3000
export TARKO_HOST=0.0.0.0

# Debug settings
export DEBUG=tarko:*
export TARKO_LOG_LEVEL=debug

# Workspace
export TARKO_WORKSPACE=./my-workspace

Exit Codes

CodeDescription
0Success
1General error
2Configuration error
3Network error
4Authentication error
5Agent execution error

Examples

Development Workflow

# 1. Initialize workspace
tarko workspace --init --name my-project

# 2. Start development with UI
tarko run --dev --open

# 3. Test with headless mode
tarko run --headless --input "Test my agent"

# 4. Deploy to production
tarko serve --port 3000 --config production.config.ts

CI/CD Integration

# Test agent functionality
tarko run agent-tars --headless --input "Run tests" --format json > results.json

# Validate configuration
tarko --dry-run --show-config

# Health check
curl -f http://localhost:3000/api/v1/health || exit 1

Debugging

# Debug with verbose logging
DEBUG=tarko:* tarko run --debug --verbose

# Test direct LLM requests
tarko request --provider openai --model gpt-4 --body '{"messages":[{"role":"user","content":"Hello"}]}' --debug

# Inspect configuration
tarko --show-config --debug