cursortoys-cli

Command-line utilities for CursorToys: HTTP testing, skill management, automation, and productivity tools.

Current version: 0.6.0

Features

• HTTP Testing: Run .req, .request, .http, and .rest files as automated tests
• Skill Management: Create and manage AI agent skills
• LLM Instructions: Built-in usage guide for LLMs
• Productivity Tools: Utilities for development workflow

Requirements

• Node.js 18+
• curl installed and on PATH (for HTTP testing)

Installation

Install Globally

npm install -g cursortoys-cli

Use with npx (no installation)

npx cursortoys http test

Local Development

cd cursorToys-cli
npm install
npm run build
npm link

Commands

HTTP Testing

Run HTTP request files (.req, .request, .http, .rest) from the project's http folder as automated tests. Uses the same format and behavior as the CursorToys VS Code extension (REST Client format, # @var, # @env, {{VAR}}, project-root .env files).

Run all HTTP tests

From the project root (where .cursor/http/ or your configured base folder lives):

cursortoys http test

Discovers all HTTP request files under the http folder (recursively), runs every request block in each file, and reports pass/fail. A request passes when status is 2xx, or when all @assert blocks pass (assertions override status).

Run a single file or folder

cursortoys http test --file path/to/file.req
cursortoys http test -f .cursor/http/api.req
cursortoys http test -f .cursor/http/auth
cursortoys http test --folder auth

HTTP Test Options

| Option | Description | |-------|-------------| | -p, --project <dir> | Project directory (default: current working directory) | | --base-folder <name> | Base folder name (default: cursor; or set CURSORTOYS_BASE_FOLDER) | | -e, --env <name> | Environment to use; overrides # @env in the file (default: dev) | | -t, --timeout <seconds> | Request timeout in seconds (default: 10) | | -f, --file <path> | Run a single file or all request files in a directory | | --folder <path> | Run all request files under a subfolder of the http directory | | -V, --verbose | Show request and response for each test | | --var <key=value> | Override a variable; can be repeated |

Paths (no VS Code)

• Workspace: process.cwd() or --project <dir>
• Base folder: CURSORTOYS_BASE_FOLDER or --base-folder (default: cursor)
• HTTP folder: {workspace}/.{baseFolder}/http/ (e.g. .cursor/http/)
• Environments: project root — .env, .env.dev, .env.staging, etc. (not inside http/)

HTTP Request File Format

Same as in the CursorToys extension:

• REST Client: METHOD URL then optional headers and body; multiple requests separated by ### or ## sections
• Variables: # @var VAR_NAME=value; # @env name to select environment (default uses .env)
• Substitution: {{VAR_NAME}} resolved from # @var, then from .env.{name} at project root
• System dynamic variables: {{$guid}}, {{$randomInt min max}}, {{$timestamp}}, {{$datetime}}, {{$localDatetime}}, {{$processEnv VAR}}, {{$dotenv VAR}}
• Helper functions: {{@uuid()}}, {{@randomIn(1,10)}}, etc.
• Delay: # @delay(milliseconds) before executing a block
• Assertions: block comments with @assert(...) — when present, all must pass
• Chained response (@SETTER / @GETTER): capture a value from one response and use it in the next block (or file in the same run)

Reserved hook files (directory-level setup/teardown):

• __before__.* / __after__.*: runs before / after other request files in that directory (extensions: .req, .request, .http, .rest)
• Hook files are not treated as normal tests (they don't get discovered twice).

Example:

# @env dev
# @var BASE_URL=https://api.example.com

## Get health
GET {{BASE_URL}}/health
Accept: application/json

###

## Create user
# @delay(1000)
POST {{BASE_URL}}/users
Content-Type: application/json

{"name": "John Doe"}

Chained response example (profile → repos using avatar_url):

# @var GITHUB_API=https://api.github.com
# @var GITHUB_USER=octocat

## Public user profile
GET {{GITHUB_API}}/users/{{GITHUB_USER}}
Accept: application/vnd.github+json

/*
 * @assert("Avatar URL is set", "res.body.avatar_url", "contains", "avatars")
 * @SETTER("VALUE", "res.body.avatar_url")
 */

###

## Public user repositories
# @getter VALUE
GET {{GITHUB_API}}/users/{{GITHUB_USER}}/repos?per_page=5&ref={{VALUE}}
Accept: application/vnd.github+json

/*
 * @getter("VALUE")
 * @assert("repos ok", "res.status", "equals", 200)
 */

• @SETTER("KEY", "res.body.field") — after the block's request, stores the value in KEY (same map as # @var)
• # @getter KEY or /* @getter("KEY") */ — fails early if KEY is not defined
• Use {{KEY}} in URL, headers, body, or assertion expected values
• Variables persist across blocks in the file and across files in the same http test run

Project root .env.dev:

BASE_URL=https://api.dev.example.com
API_KEY=dev-key

Verbose Mode and Overrides

• Verbose (-V): prints request (method, URL, headers, body) and response
• Environment (-e): uses .env.{name} at project root; # @env default maps to .env
• Variable overrides (--var KEY=value): override file and env values for the run

Examples:

cursortoys http test -V
cursortoys http test -e staging --var BASE_URL=https://staging.example.com
cursortoys http test -f .cursor/http/api.req --verbose --var API_KEY=xxx
cursortoys http test --folder integrations

Skill Management (skills)

Create, install official skills, and import from GitHub — parity with the CursorToys extension.

cursortoys skills add my-skill
cursortoys skills add http-testing -d "Skill for testing HTTP APIs"
cursortoys skills add api-docs -t project -p /path/to/project

# Official bundled skills (see `skills list`)
cursortoys skills install              # default: http (HTTP .req docs)
cursortoys skills install cli          # CLI commands and flags
cursortoys skills install http -t project -p .
cursortoys skills install http --force

# Import full skill folder from GitHub (/tree/{branch}/{folder})
cursortoys skills import https://github.com/org/repo/tree/main/path/to/skill-folder -t project -p .

cursortoys skills list

| Subcommand | Description | |------------|-------------| | add <name> | Create SKILL.md from template | | install [name] | Install bundled skill (http, cli) | | import <url> | Import skill folder from GitHub (requires SKILL.md at folder root) | | list | List official bundled skills |

Shared options for add, install, and import:

| Option | Description | |-------|-------------| | -t, --target <type> | personal or project (default: personal) | | -p, --project <dir> | Project directory (required if target is project) | | --base-folder <name> | Base folder name (default: cursor) | | -f, --force | Overwrite existing skill (install / import) | | -d, --description <text> | Skill description (add only) |

GitHub import URL format: https://github.com/{owner}/{repo}/tree/{branch}/{folder} (HTTPS only). Unauthenticated API rate limit applies (~60 requests/hour).

Deprecated: cursortoys skill … still works but prints a deprecation notice — use skills.

Bundled skills: http (cursor-toys-http) — HTTP .req files, hooks, @SETTER/@GETTER; cli (cursortoys-cli) — CLI commands, flags, and CI usage.

LLM Instructions

# Full instructions (llms.txt)
cursortoys --llm

# Filter by topic (case-insensitive)
cursortoys --llm --grep http

# Line numbers only
cursortoys --llm --grep http --indices

# Section index (## / ### headings)
cursortoys --llm --indices

HTTP Test Output

  ✓ .cursor/http/health.req 200 OK
  ✓ .cursor/http/users.req (2/3) 201 Created

Tests: 2 passed, 2 total
Time: 1.23s

Exit code is 0 if all tests passed, 1 if any failed or no files were run.

Environment Variables

| Variable | Description | |----------|-------------| | CURSORTOYS_BASE_FOLDER | Default base folder (default: cursor) | | CURSORTOYS_DEFAULT_ENV | Default environment when not set in file (default: dev) |

Integration with CursorToys Extension

The CLI matches the CursorToys VS Code extension (v2026.6.11+ for HTTP extensions):

• Same .req, .request, .http, and .rest file format
• REST Client system dynamic variables ({{$guid}}, {{$timestamp}}, {{$dotenv}}, etc.)
• Project-root .env* files (not under http/)
• Same base folder configuration
• Directory hooks (__before__ / __after__), @SETTER / @GETTER chaining, and @assert blocks
• Compatible with Cursor AI Agent Skills (skills add, install, import)

License

MIT