ora Documentation

Installation

ora is a single file — no installer, no dependencies, no runtime. The install script detects your platform automatically and puts the binary in your PATH.

macOS (Apple Silicon & Intel)

Step 1: Open the Terminal app. You can find it in Applications → Utilities → Terminal, or press Cmd + Space and type "Terminal".

Step 2: Paste this command and press Enter:

curl -sSL https://oracommand.com/install.sh | sh

You may be asked for your password — this is so ora can be placed in /usr/local/bin/ where your system can find it.

Step 3: Verify it installed correctly:

ora --version

You should see something like ora 0.1.2. That's it — ora is ready to use.

Troubleshooting: If you get a "permission denied" error, the script will save ora to your current folder instead. Move it manually:

sudo mv ./ora /usr/local/bin/ora

Linux (x86_64)

Step 1: Open your terminal.

Step 2: Run the install script:

curl -sSL https://oracommand.com/install.sh | sh

Step 3: Verify:

ora --version

If you don't have curl, use wget:

wget -qO- https://oracommand.com/install.sh | sh

Windows

Step 1: Download the binary directly:

Download ora-windows-amd64.exe

Step 2: Rename it to ora.exe and move it to a folder in your PATH (e.g. C:\Users\YourName\bin\).

Step 3: Open Command Prompt or PowerShell and run:

ora --version

Manual download

If you prefer to download the binary directly, all releases are available on GitHub:

github.com/oracommand/ora/releases

Download the file for your platform, make it executable (chmod +x ora), and move it anywhere on your PATH.

Updating

ora can update itself:

# Upgrade to the latest version
ora update

# Check what's available without installing
ora update --check

# Install a specific version
ora update --version 0.1.0

# Force reinstall
ora update --force

Or just re-run the install script — it always downloads the latest version.

First Queries

ora is a CLI. You pass your question with -q and control behavior with flags. Here are real queries you can run right now:

Basic question

Just ask something. ora runs a reasoning loop with defaults (critique strategy, up to 10 iterations, $1 budget).

ora -q "what is the best database for time series data?"

Pick a model

Use --model to choose any model from any provider.

ora -q "explain quantum tunneling simply" --model gpt-4o

Control depth

Set how many iterations ora runs. More iterations = more refinement = better answer.

ora -q "design a rate limiter for a REST API" --min-iter 3 --max-iter 15

Set a budget

Cap spending per run. ora stops gracefully and returns the best answer found.

ora -q "full competitive analysis of EV market" --budget 0.50

Choose a strategy

Three strategies: critique (default), debate (two perspectives), research (breaks into sub-questions).

ora -q "postgres vs mongodb for IoT?" --strategy debate

Save the output

ora -q "summarize Q1 metrics" --save report.md

Quiet mode — just the answer

ora -q "what is a monad?" --quiet

Dry run — see what would happen

Estimate cost and time without making any API calls.

ora -q "analyze this codebase" --model claude-opus-4-5 --max-iter 10 --dry-run

Combine flags

Flags compose freely. This runs a deep research query with Claude, capped at $0.50, saving to a file:

ora -q "comprehensive analysis of AI regulation in the EU" \
  --model claude-opus-4-5 \
  --strategy research \
  --min-iter 5 --max-iter 20 \
  --budget 0.50 \
  --save eu-ai-regulation.md

Provider Setup

ora works with any AI provider. Set your API key:

# Anthropic (Claude)
ora config set anthropic-key sk-ant-...

# OpenAI (GPT)
ora config set openai-key sk-...

# Google (Gemini)
ora config set google-key AIza-...

# Or use environment variables
export ORA_ANTHROPIC_KEY=sk-ant-...

ora auto-detects the provider from the model name: claude-* → Anthropic, gpt-* → OpenAI, gemini-* → Google.

For Ollama (local models), no API key needed:

ora -q "explain recursion simply" --model llama3.2

For any OpenAI-compatible endpoint:

ora -q "summarize this article" --model mixtral-8x7b --endpoint https://api.together.xyz/v1

How ora Works

Instead of a single API call, ora runs an iterative loop:

iter 1:  answer(prompt)                        → answer_v1
iter 2:  critique(answer_v1) → refine(critique) → answer_v2
iter 3:  critique(answer_v2) → refine(critique) → answer_v3
...
stop:    confidence >= threshold OR budget reached OR max iterations

Each iteration, the model scores its own confidence (0.00–1.00). ora returns the highest-confidence answer across all iterations — not necessarily the last one.

Strategies

Critique (default)

Answer → critique → refine → repeat. Best for most queries.

ora -q "review my API design" --strategy critique

Debate

Two perspectives (advocate + skeptic) debate, then synthesize. Best for nuanced topics.

ora -q "postgres vs mongodb for IoT?" --strategy debate

Research

Decomposes into sub-questions, answers each, synthesizes. Best for complex research.

ora -q "full EV market analysis" --strategy research

Confidence & Stopping

ora stops when any of these conditions are met:

1. Confidence reaches the threshold (default: 0.85)
2. Budget is exhausted
3. Max iterations reached
4. Convergence detected (confidence barely changing for 3 iterations)

ora always runs at least --min-iter iterations regardless of confidence.

ora -q "is this migration safe?" --confidence 0.95  # higher bar
ora -q "deep security audit" --min-iter 5       # at least 5 iterations

Budget Control

Set a per-run spending cap in USD:

ora -q "competitive analysis" --budget 0.50

# Check your spending
ora cost
ora cost --by-model

ora warns at 80% of budget and stops gracefully at the limit, returning the best answer found so far.

Memory & ContinuePro

Chain runs together using previous answers as context:

# Inject a previous run's output
ora -q "go deeper on point 3" --memory ora-1

# Inject last 3 runs
ora -q "what patterns do you see?" --memory last:3

# Continue — inherits model, system prompt, strategy
ora -q "expand on the risk section" --continue last

Prompt CraftingPro

Let ora optimize your prompt before running:

# Craft from intent
ora --craft "analyze the EV market every Monday"

# Improve a weak prompt
ora --craft --improve "tell me about stocks"

# Interactive workflow builder
ora --guide

--craft generates an optimized prompt plus ready-to-run commands. --guide walks you through building a workflow step by step.

Context Files & URLs

ora -q "summarize this" --context report.pdf
ora -q "critique this" --context https://example.com/article
ora -q "compare these" --context doc1.pdf --context doc2.pdf

ora strips HTML, enforces size limits, and warns about potential prompt injection.

Dashboard

Live terminal UI showing all processes and costs:

ora dashboard

Navigate with arrow keys. Enter to view, K to kill, Q to quit.

Web Chat Interface New

Launch a browser-based chat interface with the same reasoning engine as the CLI.

ora chat

Opens http://localhost:3737 in your browser automatically.

Features

• Chat tab — conversation interface with iteration details, copy buttons, slash commands (/list, /cost, /help)
• CLI tab — terminal-style direct command input with history
• Dashboard tab — real-time stats and recent runs
• Light/dark themes — toggle with one click, saved to browser
• Docs panel — browse documentation alongside chat
• CLI preview — see the equivalent terminal command with copy button

Options

ora chat                 # start on default port
ora chat --port 4000     # custom port
ora chat --no-open       # don't auto-open browser
ora chat --stop          # stop running server

Slash Commands in Chat

/help     — show available commands
/list     — show recent runs
/cost     — show spending summary
/kill id  — terminate a process
/history  — browse past runs

Any text without / prefix is treated as a query and sent to the reasoning engine.

CLI Reference

Complete reference for every flag and subcommand.

Subcommands

ora subcommands manage processes, configuration, history, and more. Run any subcommand with --help for details.

ora list

Show running and recent processes. Use --all to include completed runs, --running for active only.

ora list
ora list --all
ora list --running

ora output

Print the final output (best answer) of a completed process. Useful for retrieving results from background runs.

ora output ora-3
ora output last

ora trace

Show the full reasoning trace for a process — every iteration, critique, confidence score, and timing detail as JSON.

ora trace ora-3
ora trace last

ora status

Show the current status of a process including model, strategy, iteration progress, cost, and confidence.

ora status ora-3
ora status last

ora kill

Terminate one or more running processes. Accepts a single ID, last, or comma-separated IDs. The best answer found so far is saved before termination.

ora kill ora-3
ora kill last
ora kill ora-1,ora-2,ora-3

ora cost

Show spending breakdown — today, this week, this month, lifetime. Filter by model or view a specific run's cost.

ora cost
ora cost --by-model
ora cost ora-3

ora config

View and modify ora configuration. Settings are saved to ~/.ora/config.toml.

ora config show
ora config set model claude-opus-4-5
ora config set budget 0.50
ora config set anthropic-key sk-ant-...
ora config set-model llama3 ollama
ora config reset model
ora config clear

ora history

Browse and search past runs. Filter by model, strategy, date, or keyword. Export as JSON or CSV.

ora history
ora history --search "database"
ora history --model gpt-4o --since 2026-03-01
ora history --export json > history.json

ora dashboard

Open a live terminal UI showing all processes and cost breakdown. Press q or Esc to exit.

ora dashboard

ora prompts

Manage your saved prompt library. Save, list, and delete both query prompts and system prompts.

ora prompts
ora prompts --save "market-analysis=Analyze current market trends for..."
ora prompts --save-system "analyst=You are a senior financial analyst..."
ora prompts --delete market-analysis
ora prompts --systems

ora update

Check for and install new versions. ora downloads the correct binary for your platform and replaces itself atomically.

ora update
ora update --check
ora update --version 0.1.0
ora update --force

ora test

Verify your installation and API connectivity. Use --dry-run to validate config without making API calls.

ora test
ora test --dry-run
ora test --model gpt-4o

ora export

Export a completed run to a file. Supports markdown and JSON formats.

ora export ora-3 --format markdown
ora export last --format json

ora clean

Remove old process files and artifacts. Preview with --dry-run before deleting.

ora clean --older-than 30d
ora clean --keep-last 50
ora clean --dry-run
ora clean --sockets
ora clean --disk

Flags

Flags modify how ora runs a query. Combine any number of flags in a single command.

-q / --query

The question or prompt to send to the reasoning engine. Required for running a query. Accepts an inline string, a path to a text file, or piped input via -.

ora -q "what is the best database for time series?"
ora -q "explain quantum computing" --model gpt-4o
ora -q prompts/research.txt
echo "what is Rust?" | ora -q -
echo "what is Rust?" | ora

--model

Choose which AI model to use. ora auto-detects the provider from the model name. You can also use the explicit provider/model format. Default: claude-sonnet-4-20250514.

ora -q "explain quantum computing" --model claude-opus-4-5
ora -q "design a REST API" --model gpt-4o
ora -q "summarize this paper" --model gemini-2.0-flash
ora -q "write a Python script" --model llama3.2
ora -q "explain microservices" --model openai/gpt-4o
ora -q "review this code" --model anthropic/claude-sonnet-4-20250514
ora -q "translate to Spanish" --model meta/llama-3-70b

--strategy

Select the reasoning strategy. critique (default) iteratively refines a single answer. debate pits an advocate against a skeptic and synthesizes. research decomposes the question into sub-questions, answers each, and merges the results.

ora -q "improve my landing page copy" --strategy critique
ora -q "should we migrate to microservices?" --strategy debate
ora -q "full EV market analysis" --strategy research
ora -q "should we use Kubernetes?" --strategy debate --max-iter 15

--min-iter / --max-iter

Control iteration bounds. --min-iter guarantees a minimum number of reasoning passes regardless of confidence. --max-iter sets the upper limit. Defaults: min 2, max 10.

ora -q "full market analysis" --min-iter 5 --max-iter 20
ora -q "quick check" --max-iter 3
ora -q "deep analysis" --min-iter 8
ora -q "what is 2+2" --min-iter 1 --max-iter 1

--confidence

Set the confidence threshold at which ora stops iterating. The model self-scores each answer from 0.00 to 1.00. When confidence meets or exceeds this value (and --min-iter is satisfied), the loop ends. Default: 0.85.

ora -q "is this SQL injection safe?" --confidence 0.95
ora -q "rough draft" --confidence 0.70
ora -q "verify this proof" --confidence 0.99 --max-iter 30
ora -q "brainstorm startup ideas" --confidence 0.80 --min-iter 5

--budget

Set a per-run spending cap in USD. ora warns at 80% and stops gracefully at the limit, returning the best answer found so far. Prevents runaway costs on long-running queries. Minimum budget is $0.001. Zero budget is not allowed.

ora -q "analyze competitor pricing" --budget 0.50
ora -q "deep research" --budget 2.00 --strategy research
ora -q "quick summary" --budget 0.10 --model gpt-4o
ora -q "research AI regulation" --budget 0.25 --max-iter 20

--system

Set a system prompt to steer the model's behavior. Pass an inline string, a file path, or reference a saved prompt with @name. The system prompt is included in every iteration of the reasoning loop.

ora -q "review this Go code" --system "You are a senior Go engineer."
ora -q "edit this draft" --system prompts/editor.txt
ora -q "check for bugs" --system @code-reviewer
ora -q "summarize the meeting" --system "Respond only in bullet points."

--memoryPro

Inject the output of a previous run as additional context. Reference a specific run by ID or use last / last:N to pull the most recent runs. Useful for building on earlier reasoning without re-running.

ora -q "go deeper on point 3" --memory ora-1
ora -q "summarize the findings" --memory last
ora -q "what patterns do you see?" --memory last:3
ora -q "compare these results" --memory ora-5 --memory ora-7

--continuePro

Continue from a previous run. Unlike --memory, this inherits the model, system prompt, strategy, and full conversation context from the referenced run. Effectively resumes a reasoning session.

ora -q "expand on the risk section" --continue last
ora -q "now compare with competitors" --continue ora-3
ora -q "add a conclusion" --continue last --max-iter 5
ora -q "refine the introduction" --continue ora-12

--context

Attach files or URLs as context for the query. ora reads the content, strips HTML from web pages, enforces size limits, and warns about potential prompt injection. Pass multiple times to attach several sources.

ora -q "summarize this" --context report.pdf
ora -q "critique this article" --context https://example.com/post
ora -q "compare these" --context doc1.pdf --context doc2.pdf
ora -q "review this code" --context src/main.go --context src/utils.go

--output

Set the output format. text (default) prints the answer as plain text. json returns structured data including confidence, cost, and iteration details. markdown outputs with Markdown formatting preserved.

ora -q "explain Docker" --output text
ora -q "analyze this data" --output json
ora -q "write documentation" --output markdown
ora -q "analyze this data" --output json --quiet | jq -r '.answer'

--save

Save the final answer to a file. The file is written after the run completes (or after the best answer is selected if the budget is hit). Works with any output format.

ora -q "summarize Q1 metrics" --save report.md
ora -q "analyze sales data" --save output.json --output json
ora -q "market trends 2026" --save analysis.txt --strategy research

--quiet

Suppress all progress output (iteration counts, confidence scores, timing). Only the final answer is printed. Useful for scripting and piping ora's output into other tools.

ora -q "what is a monad?" --quiet
ora -q "evaluate this risk" --quiet --output json | jq '.confidence'
ora -q "next action item" --quiet >> answers.txt
ora -q "one-line summary" --quiet --model gpt-4o

--verbose

Enable debug output. Shows full request/response payloads, token counts per iteration, internal scoring details, and timing breakdowns. Useful for diagnosing unexpected behavior or understanding cost.

ora -q "explain OAuth 2.0" --verbose
ora -q "monolith vs microservices" --verbose --strategy debate
ora -q "full code audit" --verbose --dry-run
ora -q "debug this error" --verbose 2>debug.log

--dry-run

Estimate cost, token usage, and iteration count without making any API calls. Shows what ora would do, how much it would likely cost, and how long it would take. No money is spent.

ora -q "deep research" --dry-run
ora -q "comprehensive analysis" --model claude-opus-4-5 --max-iter 20 --dry-run
ora -q "industry report" --strategy research --dry-run
ora -q "summarize this document" --context largefile.pdf --dry-run

--craftPro

Optimize your prompt before running. Pass an intent or rough idea, and ora generates a refined prompt plus ready-to-run commands. Use --improve alongside to refine an existing prompt instead of starting from scratch.

ora --craft "analyze the EV market every Monday"
ora --craft --improve "tell me about stocks"
ora --craft "weekly security audit of our repos"
ora --craft "compare cloud providers for our workload"

--guidePro

Launch the interactive workflow builder. ora walks you through choosing a model, strategy, iteration bounds, budget, and system prompt step by step. Outputs a ready-to-run command at the end.

ora --guide
ora --guide --model gpt-4o
ora --guide --strategy research
ora --guide --budget 1.00

--endpoint

Point ora at a custom OpenAI-compatible API endpoint. Useful for self-hosted models, third-party providers, or corporate proxies. Combine with --model to specify the model name the endpoint expects.

ora -q "translate to French" --model mixtral-8x7b --endpoint https://api.together.xyz/v1
ora -q "write unit tests" --model llama3 --endpoint http://localhost:11434/v1
ora -q "internal analysis" --endpoint https://corp-proxy.internal/v1
ora -q "classify this text" --model custom-ft --endpoint https://api.fireworks.ai/v1

--no-color

Disable colored output. Useful when piping to files, running in CI environments, or using terminals that do not support ANSI color codes.

ora -q "explain Kubernetes" --no-color
ora -q "generate report" --no-color >> log.txt
ora -q "debug this issue" --no-color --verbose 2>&1 | tee debug.log
ORA_NO_COLOR=1 ora -q "run analysis"

JSON Output

Use --output json --quiet for structured output in pipelines:

{
  "schema_version": 1,
  "id": "ora-3",
  "status": "done",
  "stopped_by": "confidence_threshold",
  "answer": "...",
  "confidence": 0.91,
  "iterations": { "completed": 4, "min": 2, "max": 10 },
  "cost": { "total_usd": 0.18, "tokens_in": 8200, "tokens_out": 4100 }
}

# Extract answer
ora -q "analyze this data" --output json --quiet | jq -r '.answer'

# Check confidence
ora -q "evaluate this claim" --output json --quiet | jq '.confidence > 0.85'

Configuration

Config lives at ~/.ora/config.toml:

ora config show                          # view all settings
ora config set model claude-opus-4-5      # default model
ora config set budget 1.00               # default budget
ora config set min-iter 2                # default min iterations
ora config set max-iter 10               # default max iterations
ora config set strategy critique         # default strategy
ora config set confidence 0.85           # default threshold

Priority: explicit flags > environment variables > config file > defaults.

Cost Tracking

ora tracks the cost of every run automatically. Costs are based on the token pricing set by each AI provider — ora uses whatever the model charges. You pay your provider directly; ora just tracks it for you.

# See your spending
ora cost                   # today, week, month, lifetime
ora cost --by-model        # breakdown by model

# Estimate before running
ora -q "full research project" --dry-run

# Set a budget cap
ora -q "competitor analysis" --budget 0.50

Local models (Ollama) are free. For cloud models, check your provider's pricing page for current rates. ora will never spend more than your --budget.

Integrations

ora works with any AI provider. Here's how to connect each one.

# Run directly
ora -q "your question"

# Use in a bash script
#!/bin/bash
ANSWER=$(ora -q "analyze this data" --output json --quiet | jq -r '.answer')
echo "$ANSWER" > report.md

# Pipe data in
cat error.log | ora -q "what went wrong?" --quiet

# Use in Makefile
analyze:
	ora -q "review this codebase" --context src/ --save review.md

ora config set anthropic-key sk-ant-your-key-here

ora -q "explain general relativity" --model claude-opus-4-5
ora -q "review this PR" --model claude-sonnet-4-20250514
ora -q "quick fact check" --model claude-haiku-4-5

ora config set openai-key sk-your-key-here

ora -q "design a database schema" --model gpt-4o
ora -q "summarize in one line" --model gpt-4o-mini
ora -q "solve this math problem" --model o3

ora config set google-key AIza-your-key-here

ora -q "quick translation" --model gemini-2.0-flash
ora -q "research this topic" --model gemini-2.0-pro

ollama pull llama3.2

ora -q "explain this locally" --model llama3.2
ora -q "write a poem" --model mistral
ora -q "reason through this" --model deepseek-r1

curl -sSL https://oracommand.com/install.sh | sh

# Agent calls ora and gets structured JSON back
RESULT=$(ora -q "analyze this customer feedback for sentiment" --output json --quiet)

# Parse the fields OpenClaw needs
ANSWER=$(echo $RESULT | jq -r '.answer')
CONFIDENCE=$(echo $RESULT | jq -r '.confidence')
COST=$(echo $RESULT | jq -r '.cost.total_usd')

# Use in your OpenClaw pipeline
echo "Answer: $ANSWER"
echo "Confidence: $CONFIDENCE"
echo "Cost: $COST"

# Step 1: Research phase
ora -q "gather key metrics for Q1" --strategy research --save step1.md

# Step 2: Analysis phase (uses step 1 as context)
ora -q "identify trends and risks" --context step1.md --save step2.md

# Step 3: Recommendation phase
ora -q "write executive recommendations" --context step1.md --context step2.md --save final.md

# Each ora call capped at $0.25
ora -q "step 1" --budget 0.25 --output json --quiet
ora -q "step 2" --budget 0.25 --output json --quiet

# Check total pipeline spend
ora cost

{
  "status": "done",
  "answer": "...",
  "confidence": 0.91,
  "iterations": { "completed": 4 },
  "cost": { "total_usd": 0.0234 }
}

# Together AI
ora -q "analyze in French" --model mixtral-8x7b --endpoint https://api.together.xyz/v1

# Groq
ora -q "complex reasoning task" --model llama-70b --endpoint https://api.groq.com/openai/v1

# Self-hosted (vLLM, llama.cpp, etc.)
ora -q "custom task" --model my-model --endpoint http://localhost:8080/v1

# Save to config so you never type the endpoint again
ora config set-model mixtral-8x7b custom:https://api.together.xyz/v1

How To Use ora

Practical examples from getting started to advanced.

Getting Started

Intermediate

Advanced — Pro

These features require ora Pro. Sign up at oracommand.com/pro

Troubleshooting

Quick fixes for common issues.

ora: command not found

The binary isn't in your PATH. Re-install:

curl -sSL https://oracommand.com/install.sh | sh

Or check where it was installed:

which ora || ls /usr/local/bin/ora

macOS: "cannot be opened because it is from an unidentified developer"

xattr -d com.apple.quarantine /usr/local/bin/ora

API key not working / plan shows "free" after upgrade

Your CLI may have an old or wrong key. Get your current key from your account page and reset it:

# Check your current key
ora account status

# If wrong, get your key from https://oracommand.com/account
# Then update it:
ora account set-key ora_YOUR_KEY_HERE

Pro features still blocked after upgrading

ora checks your plan with a fresh API call every time for free users. Just run the command again — it should work immediately after upgrading. If not:

# Force a fresh check
ora account status

# If it still shows "free", your key may be stale
# Login at oracommand.com → copy key from Account page
ora account set-key ora_YOUR_NEW_KEY

API errors (rate limit, invalid key, model not found)

# Check your provider keys
ora config show

# Re-set a provider key
ora config set anthropic-key sk-ant-YOUR-KEY

# Test connectivity
ora test --dry-run
ora test

Cost showing $0.0000

This happens with streaming responses where the provider doesn't return token counts. ora estimates from content length. The cost tracking works correctly for non-streaming calls.

Regenerate your API key

If you think your key is compromised or want a fresh one:

# On the website: oracommand.com/account → Regenerate API Key
# Then update in terminal:
ora account set-key ora_YOUR_NEW_KEY

Uninstall ora

ora uninstall
# To also remove data:
rm -rf ~/.ora/

Stop a running query

Press Ctrl+C to interrupt a running query. ora saves the best answer found so far and exits.

Still stuck?

Run the diagnostic command and email us:

ora bug-report

Send the output to hello@oracommand.com