@runtypelabs/cli 0.1.9 → 0.2.0

package/README.md

@@ -10,6 +10,12 @@ Command-line interface for the Runtype AI platform.
 npm install -g @runtypelabs/cli
 ```
 
+Or run without installing:
+
+```bash
+npx @runtypelabs/cli <command>
+```
+
 ## Quick Start
 
 ### 1. Create Account & Authenticate
@@ -54,6 +60,27 @@ runtype records create --name "My Record" --type "document"
 runtype records list --type document
 ```
 
+### 4. Run Multi-Session Agent Tasks
+
+Use `runtype marathon` (or `runtype agents task`) to run long-running, multi-session agent tasks with real-time streaming output.
+
+```bash
+# Run a task — agent output streams to your terminal in real time
+runtype marathon "Code Builder" -m "Refactor the auth module to use JWT tokens"
+
+# Set a budget and session limit, save progress with a custom name
+runtype marathon agent_abc123 -m "Write integration tests for the API" \
+  --max-sessions 10 --max-cost 2.50 --name "api-tests"
+
+# Resume an interrupted task (picks up where it left off)
+runtype marathon "Code Builder" -m "Refactor the auth module to use JWT tokens" \
+  --resume --name "auth-refactor" --debug
+
+# Sync progress to a Runtype record (visible in the dashboard)
+runtype marathon "Code Builder" -m "Build the payments integration" \
+  --max-sessions 20 --track --name "payments"
+```
+
 ## Chat Commands
 
 During a chat session, you can use these special commands:
@@ -132,17 +159,22 @@ node dist/index.js talk
 **Option 3: Install globally for testing**
 
 ```bash
-# Build and install globally
+# Build first
 pnpm build
-npm install -g .
 
+# Option A: Symlink (pnpm) — global runtype uses your local package; rebuild after changes
+# If you get "Unable to find the global bin directory", run: pnpm setup (then restart terminal)
+pnpm link --global
+# Use anywhere: runtype --help, runtype products init --from <url>, etc.
+# To stop: pnpm unlink --global (from packages/cli)
+
+# Option B: Install current directory (npm)
+npm install -g .
 # Now use the runtype command anywhere
 runtype --help
 runtype auth login
 runtype talk
-
-# After making changes, rebuild and reinstall
-pnpm build && npm install -g .
+# After making changes, rebuild and reinstall: pnpm build && npm install -g .
 ```
 
 ### Local Environment Configuration
@@ -163,6 +195,33 @@ RUNTYPE_DEFAULT_TEMPERATURE=0.7
 DEBUG=true
 ```
 
+### Testing against local API
+
+To use the CLI with your local API and dashboard:
+
+1. **Run API and dashboard** (from repo root): `pnpm dev:api` (or `pnpm dev:bun`) and `pnpm dev:dashboard`. Ensure the dashboard has `NEXT_PUBLIC_RUNTYPE_API_URL=http://localhost:8787` so CLI auth creates keys against your local API.
+
+2. **Use a `.env` in `packages/cli`** with `RUNTYPE_API_URL` and `RUNTYPE_DASHBOARD_URL` as above, or set them when running:
+
+   ```bash
+   RUNTYPE_DASHBOARD_URL=http://localhost:3001 RUNTYPE_API_URL=http://localhost:8787 pnpm dev -- auth login
+   ```
+
+3. **Or skip browser auth** by creating an API key in the local dashboard, then:
+   ```bash
+   RUNTYPE_API_URL=http://localhost:8787 pnpm dev -- auth login --api-key YOUR_API_KEY
+   ```
+
+**Testing a single command** (from `packages/cli`):
+
+```bash
+export RUNTYPE_DASHBOARD_URL=http://localhost:3001
+export RUNTYPE_API_URL=http://localhost:8787
+pnpm dev -- agents list
+```
+
+Or inline: `RUNTYPE_DASHBOARD_URL=http://localhost:3001 RUNTYPE_API_URL=http://localhost:8787 pnpm dev -- flows list`
+
 ### Testing
 
 ```bash
@@ -175,7 +234,7 @@ pnpm test:watch
 
 ## Environment Variables
 
-- `RUNTYPE_API_URL` - API endpoint URL (default: https://api.runtype.com)
+- `RUNTYPE_API_URL` - API base URL **without** a path (e.g. `http://localhost:8787`). Do not include `/v1`; the CLI adds the version prefix. Default: https://api.runtype.com
 - `RUNTYPE_DASHBOARD_URL` - Dashboard URL (default: https://use.runtype.com)
 - `CLERK_PUBLISHABLE_KEY` - Clerk public key for OAuth
 - `RUNTYPE_DEFAULT_MODEL` - Default AI model (default: gpt-4o)