Orkhub CLI

Scaffold, run, test, and publish AI agents from your terminal. The CLI is a thin client over the Orkhub API — your code lives locally (edit it, commit it), and runs on Orkhub’s cloud sandboxes, streaming the live trace back to your terminal.

v0.3.0Node 18+

Installation

Install globally so orkhub is on your PATH:

npm install -g orkhub
orkhub version

Working from the monorepo? Link it locally instead:

cd cli
npm run sync-sdk   # bundle the Python SDK into the package
npm link           # puts 'orkhub' on your PATH

orkhub version
# orkhub 0.1.0

Or run it directly without linking: node cli/bin/orkhub.mjs <command>.

Quickstart

1. Create an API key
Open Developers → API keys, create a key, and copy the ork_… value (shown once).

2. Log in

orkhub login
# Orkhub URL [https://orkhub.vercel.app]:
# API key: ork_…

3. Scaffold, push, run

orkhub init my-agent
cd my-agent
orkhub push                 # upload to Orkhub
orkhub run -m "hello"       # run it on Orkhub, trace streams here

4. Ship it

orkhub test       # run your evals
orkhub publish    # validate → test → snapshot → marketplace

Authentication

The CLI uses an API key — no OAuth. It’s stored in ~/.orkhub/config.json and sent only to the Orkhub URL you target. For CI, set ORKHUB_API_KEY andORKHUB_API_URL in the environment (they override the saved config), or pass --key / --url to login.

# CI example
export ORKHUB_API_KEY=ork_…
export ORKHUB_API_URL=https://orkhub.vercel.app
orkhub push && orkhub publish

Commands

orkhub init <name>

Scaffold

Creates ./<name> with orkhub.yaml, agent.py, ui.json, evals.yaml, requirements.txt, README.md, and the bundled orkhub/ Python SDK — a runnable chat agent you can edit and commit.

orkhub init my-agent
orkhub init "Support Bot" --dir support-bot

--dir <path>

Target directory (defaults to the slugified name).

orkhub login

Auth

Saves and verifies your API key against /api/auth/me.

--key <ork_…>

Provide the key inline (e.g. for CI).

--url <url>

Orkhub base URL.

Default: https://orkhub.vercel.app

orkhub whoami / logout

Auth

whoami prints the logged-in account; logout removes the saved key.

orkhub push

Upload

Creates the agent on Orkhub (or updates it if the slug exists) and uploads every file in the current folder. Reads the slug/name from orkhub.yaml. Remembers the agent id in .orkhub/agent.json for later commands.

orkhub run -m "<message>"

Run

Runs the agent on an Orkhub cloud sandbox and streams the trace (tool calls, thinking, result) to your terminal. If the agent pauses for approval, input, a choice, or a form, the CLI prompts you right there and resumes.

-m, --message <text>

The user message (prompts if omitted).

--slug <slug>

Target a specific agent instead of the current folder.

orkhub dev

Local loop

An interactive REPL: type messages and see each run’s trace + reply. Edit your code and run orkhub push in another shell to update the cloud copy.

orkhub generate "<description>"

AI build

Builds an agent from a plain-English description using the same plan → build → test → repair loop as the web builder, streaming progress to your terminal.

orkhub test

Runs the cases in evals.yaml against the agent and prints pass/fail per case.

orkhub publish

Ship

Validates, runs evals, snapshots the sandbox, and publishes a new version to the marketplace. Prints the live listing URL on success.

orkhub.yaml

The manifest at the root of every agent. name is the slug; the prompt, model, tools, limits, and marketplace metadata all live here. agent.py wires tools to Agent.from_manifest().

schema_version: "1.0"
name: company-research
display_name: "Company Research Agent"
description: "Input a company URL — get a one-page brief."
runtime: python
runtime_version: "3.12"

model:
  profile: balanced        # speed | balanced | quality

system_prompt: |
  You research a company from its URL and produce a concise brief.

tools:
  - builtin: web_fetch

deploy:
  - http

limits:
  max_tokens_per_run: 50000
  max_tool_calls_per_run: 20
  max_runtime_seconds: 120
  max_cost_usd_per_run: 1.00

marketplace:
  category: data
  pricing:
    starter: { monthly_usd: 0, tasks_included: 50 }
  tags: [research, sales]

Config file

Stored at ~/.orkhub/config.json:

{
  "apiUrl": "https://orkhub.vercel.app",
  "apiKey": "ork_…"
}

Prefer no code?

The GUI builder covers the same workflow in a browser.

Open the builder →