AI skill

Rig ships an installable skill so your AI agent learns the rig CLI - and can start servers, tail logs, and diagnose problems while it works on your code.

Install

The skill is distributed through skills.sh. One command installs it into whichever agent you're running:

terminal
$ npx skills add infinode/rig

It works with Claude Code, Cursor, and any other agent skills.sh supports. You'll need Rig installed and running, and the rig CLI on your PATH (rig install).

What the agent can do

  • List and inspect projects, ports, and process status.
  • Start, stop, and restart dev servers on demand.
  • Stream and filter logs while reproducing a bug.
  • Free a stuck port and confirm a server recovered.
  • Check DNS, proxy, and helper health with rig doctor.

Because the CLI emits structured JSON when piped, the agent gets clean, parseable data instead of scraping terminal output. See the full CLI reference.

The skill

This is the exact SKILL.mdthat gets installed - copy it directly into any agent that reads skill files if you'd rather not use the installer.

skills/rig/SKILL.md
---
name: rig
description: Use when working in a local JS/TS project managed by Rig - to start, stop, restart, or inspect dev servers, stream logs while debugging, free stuck ports, or check DNS/proxy health. Rig manages Node, Bun, and Deno dev servers and routes project.rig domains; the `rig` CLI is its scriptable interface and returns JSON when piped.
---
 
# Rig CLI
 
Rig is a macOS app that manages local JavaScript/TypeScript dev servers (Node,
Bun, Deno). It auto-discovers projects, assigns stable ports, runs dev servers,
and routes `project.rig` domains. The `rig` CLI is how you drive it.
 
## Before anything else
 
Confirm Rig is running and the CLI can reach it:
 
```bash
rig status
```
 
If this exits with code `4` (`{"error":"Rig is not running","code":"APP_NOT_RUNNING"}`),
the desktop app isn't open. Ask the user to launch Rig; do not try to start dev
servers yourself with `npm`/`pnpm`/`bun` as a workaround unless the user asks.
 
## Output contract - rely on this
 
- When piped (i.e. when you run it), `rig` emits **raw JSON, no ANSI codes**.
- Add `--json` to force JSON in any context.
- Errors go to **stderr** as `{"error": "message", "code": "ERROR_CODE"}`.
- Exit codes: `0` ok · `1` general error · `2` not found · `3` already running ·
  `4` app not running.
- Always parse stdout as JSON. Check the exit code before trusting output.
 
Projects are addressed by **name or id** - use the name from `rig list`.
 
## Core workflow
 
```bash
rig list                      # all projects: name, framework, status, port
rig inspect <name>            # full detail: port, pid, memory, uptime, framework
rig start <name>              # start a dev server
rig stop <name>               # stop it
rig restart <name>            # restart it
rig open <name>               # open its URL in the browser
rig run <name> <script>       # run a package.json script / Deno task, streaming
```
 
## Debugging a project
 
This is the highest-value loop. To investigate a failing or misbehaving server:
 
```bash
rig logs <name>               # last 100 lines as JSON
rig logs <name> --since 5m    # only the last 5 minutes (5m, 1h, ...)
rig logs <name> --follow      # stream new lines live, one JSON object per line
```
 
Each log line is `{"projectId","timestamp","level","message"}` where `level`
is `Stdout`, `Stderr`, or `System`. Filter on `Stderr` to find errors fast.
`rig logs` also accepts `-n <count>` and `--grep <text>` (case-insensitive).
 
A typical debugging pass:
1. `rig inspect <name>` - is it `Running`, `Crashed`, or `Error`? Note the port.
2. `rig logs <name> --since 10m` - read recent stderr for the actual failure.
3. Fix the code.
4. `rig restart <name>` then `rig logs <name> --follow` to confirm it recovered.
 
If a restart fails because the port is held by a stale process:
 
```bash
rig free-port <port>          # force-quit whatever is listening on that port
```
 
## Config & environment
 
```bash
rig config                            # print all settings as JSON
rig config set tld <value>            # tld | pkg-manager | node-manager | start-on-login
rig add <path>                        # watch a folder and discover projects inside it
rig dev [path]                        # discover + start a directory without watching it
rig remove <path>                     # stop watching a folder
rig node <name> [version]             # pin a Node version (omit or `auto` to clear)
rig ssl <name> <on|off>               # toggle per-project HTTPS
rig metrics <name>                    # recent memory/CPU samples
rig clear-logs <name>                 # clear a project's in-memory log buffer
rig export                            # print this machine's shareable config as JSON
rig import <file>                     # apply a shared config (or - for stdin)
rig doctor                            # health-check DNS, proxy, ports, permissions
```
 
Add folders to the watch set with `rig add <path>` (or the app's "Add folder"
button). To run a directory ad hoc without watching it, use `rig dev <path>`.
 
## Rules
 
- Prefer `rig` over launching dev servers directly - it owns ports, logs, and
  routing, and starting a second server by hand will collide.
- Don't run `rig install`, `rig config set`, or `rig ssl` without the user
  asking - these change their machine's setup.
- Privileged actions (enabling `.rig` routing, trusting the HTTPS cert) are
  GUI-only and need a macOS prompt; if `rig doctor` reports them missing, tell
  the user to enable them from the app's Doctor panel rather than scripting it.
- When reporting status to the user, summarise the JSON - don't dump it raw.

Next: Doctor & troubleshooting