How to Use Orca for Large Language Model Fine-Tuning: A Complete CLI Guide

Orca provides a first-class command-line interface called orca-cli that enables seamless fine-tuning of large language models through a secure, sandboxed OpenCode runtime.

Orca is a cross-platform desktop application built on Electron and Vite that ships with orca-cli for automation workflows. If you are working with the stablyai/orca repository, you can leverage the CLI to execute end-to-end fine-tuning jobs without interacting with the GUI, making it ideal for CI/CD pipelines and batch operations.

Understanding the Fine-Tuning Architecture

Orca implements a three-tier architecture to handle LLM fine-tuning. Understanding these layers helps debug issues and optimize your training pipeline.

The Three-Layer Architecture

The system separates concerns across distinct layers:

1. User-Facing CLI – Parses arguments, validates model identifiers, and expands shortcuts before forwarding requests to the runtime. Implementation lives in skills/orca-cli/SKILL.md.
2. Orca Runtime – Coordinates the OpenCode process, injects environment variables, and streams progress back to the UI or terminal. Core logic resides in src/shared/commit-message-plan.ts.
3. Model Registry – Maintains static definitions and dynamic discovery logic for both inference and fine-tuning operations. Defined in src/shared/commit-message-agent-spec.ts.

Model Registry and Capability Detection

Before executing a fine-tune job, Orca validates that the target model supports the fine_tune capability. The registry distinguishes between:

• Static models: Hard-coded entries like gpt-4 or claude-2
• Dynamic models: Discovered at runtime via the underlying agent's --list-models flag

The validation logic in src/shared/commit-message-plan.ts gates the CLI, ensuring orca-cli fine-tune rejects unsupported models immediately with a clear error message rather than failing mid-training.

Prerequisites and Configuration

Orca requires proper configuration before launching training jobs to ensure correct model discovery and output handling.

Configuring orca.yaml Defaults

Global defaults are stored in orca.yaml at the repository root. Relevant configuration keys include:

• defaultFineTuneModel: Fallback model when --model is omitted from CLI commands
• fineTuneDataDir: Base directory where training data files are resolved

You can override any YAML value using environment variables prefixed with ORCA_. For example, set ORCA_DEFAULT_FINE_TUNE_MODEL to change the default without modifying the configuration file.

Environment Variables and API Keys

Fine-tuning often requires external API access. Orca reads secrets like OPENAI_API_KEY from standard environment variables rather than storing them in the repository or logs. Ensure your API keys are exported in your shell before running commands:

export OPENAI_API_KEY="sk-..."
export ORCA_DEFAULT_FINE_TUNE_MODEL="openai/gpt-4"

Running Fine-Tuning Jobs with orca-cli

The orca-cli binary is built from the TypeScript source tree and installed as orca on your system. Fine-tuning follows a predictable workflow from model selection to checkpoint generation.

Listing Supported Models

First, verify which models support fine-tuning in your current environment:

orca-cli list-models --capability fine_tune

This command queries the registry defined in src/shared/commit-message-agent-spec.ts and returns only models with the fine_tune flag enabled.

The Fine-Tuning Command Syntax

The generic command structure accepts several required and optional parameters:

orca-cli fine-tune \
  --model <model-id> \
  --data <path-to-training-data> \
  [--epochs <n>] \
  [--output <output-dir>] \
  [--extra-args <...>]

Parameter descriptions:

• --model: Registry identifier (e.g., openai/gpt-4)
• --data: Path to JSONL or CSV training data
• --epochs: Number of training passes (default: 1)
• --output: Directory for the fine-tuned checkpoint
• --extra-args: Agent-specific flags passed verbatim to OpenCode

Behind the scenes, the CLI validates the model via validateModel in src/shared/commit-message-plan.ts, then spawns an OpenCode job:

opencode run \
  --agent openai \
  --task fine-tune \
  --model <model-id> \
  --data <path-to-training-data> \
  --epochs <n> \
  --output <output-dir>

Monitoring Training Progress

OpenCode handles the heavy lifting: downloading base weights, preparing optimizers, and executing the training loop. The CLI streams progress to your terminal and writes a final JSON manifest (manifest.json) to the output directory:

# Fine-tune OpenAI GPT-4 with custom epochs

orca-cli fine-tune \
  --model openai/gpt-4 \
  --data ./data/qa_pairs.jsonl \
  --epochs 3 \
  --output ./fine-tuned/gpt-4

JSON output format:

{
  "status": "fine_tune_complete",
  "model": "openai/gpt-4",
  "checkpoint": "./fine-tuned/gpt-4/checkpoint.pt",
  "epochs": 3
}

Advanced Configuration and Security

Orca implements several safeguards for production workflows involving large payloads and network operations.

Passing Extra Arguments to OpenCode

For advanced hyperparameter tuning or custom agent behaviors, use --extra-args to pass flags directly to the underlying OpenCode process:

orca-cli fine-tune \
  --model openai/gpt-4 \
  --data ./training.jsonl \
  --extra-args "--learning-rate 0.0001 --batch-size 8"

Sandboxed Execution and Permission Model

The CLI automatically executes the OpenCode process in a sandboxed child process that respects the same permission model used for standard Orb-agent execution. This prevents arbitrary code execution and ensures secrets are never exposed to untrusted processes.

Inference with Fine-Tuned Models

After training completes, use the checkpoint immediately for inference without leaving the Orca ecosystem:

orca-cli infer \
  --model ./fine-tuned/gpt-4 \
  --prompt "Explain the difference between supervised and reinforcement learning."

The path ./fine-tuned/gpt-4 refers to the output directory specified during training, which contains the serialized checkpoint and manifest.

Summary

• Orca fine-tuning is orchestrated through orca-cli, which validates models against the registry in src/shared/commit-message-agent-spec.ts before executing OpenCode jobs.
• Configuration defaults live in orca.yaml and can be overridden via ORCA_* environment variables or standard API keys like OPENAI_API_KEY.
• Security is enforced through sandboxed execution and environment-based secret management, ensuring training data and credentials remain secure.
• Workflow consists of listing capable models, running orca-cli fine-tune with JSONL/CSV data, and using the resulting checkpoint for inference via orca-cli infer.

Frequently Asked Questions

What file formats does Orca support for training data?

Orca accepts JSONL and CSV formats for the --data parameter. The CLI passes these files directly to the OpenCode runtime, which handles parsing and tokenization according to the specific agent's requirements.

How does Orca determine if a model can be fine-tuned?

The CLI checks the model registry in src/shared/commit-message-agent-spec.ts for the fine_tune capability flag. If the flag is missing, the validateModel function in src/shared/commit-message-plan.ts returns an error before spawning any training processes.

Can I fine-tune models without using the desktop GUI?

Yes. The orca-cli is designed specifically for non-interactive automation. As documented in skills/orca-cli/SKILL.md, all fine-tuning operations available in the desktop application are exposed via CLI commands, making it suitable for server environments and automated pipelines.

Where are fine-tuning checkpoints stored?

Checkpoints are written to the directory specified by the --output flag. The directory contains a manifest.json file with metadata and the model weights. If --output is omitted, the CLI uses the fineTuneDataDir from orca.yaml as the base location.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}