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

> Master Orca large language model fine-tuning with our complete CLI guide. Leverage the secure, sandboxed OpenCode runtime for efficient model adaptation. Learn to use orca-cli today.

- Repository: [Stably/orca](https://github.com/stablyai/orca)
- Tags: how-to-guide
- Published: 2026-05-25

---

**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`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/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:

```bash
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:

```bash
orca-cli list-models --capability fine_tune

```

This command queries the registry defined in [`src/shared/commit-message-agent-spec.ts`](https://github.com/stablyai/orca/blob/main/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:

```bash
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`](https://github.com/stablyai/orca/blob/main/src/shared/commit-message-plan.ts), then spawns an OpenCode job:

```bash
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`](https://github.com/stablyai/orca/blob/main/manifest.json)) to the output directory:

```bash

# 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:

```json
{
  "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:

```bash
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:

```bash
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`](https://github.com/stablyai/orca/blob/main/src/shared/commit-message-agent-spec.ts) before executing OpenCode jobs.
- **Configuration** defaults live in [`orca.yaml`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/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`](https://github.com/stablyai/orca/blob/main/manifest.json) file with metadata and the model weights. If `--output` is omitted, the CLI uses the `fineTuneDataDir` from [`orca.yaml`](https://github.com/stablyai/orca/blob/main/orca.yaml) as the base location.