cursortoys-cli

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

Features

• 🧪 HTTP Testing: Run .req / .request 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-cli http test

Local Development

cd cursorToys-cli
npm install
npm run build
npm link

Commands

HTTP Testing

Run HTTP request files (.req / .request) 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}}, .env files), without depending on VS Code.

HTTP Testing

Run all HTTP tests

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

cursortoys http test

Discovers all .req and .request files under the http folder (excluding the environments subfolder), runs the first request in each file (before the first ###), and reports pass/fail. A request is considered passed if the response status code is 2xx.

Run a single file

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

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) | | --environments-folder <name> | Environments subfolder under http (default: .environments; or CURSORTOYS_ENVIRONMENTS_FOLDER) | | -e, --env <name> | Environment to use; overrides # @env in the file (default when not set: dev) | | -t, --timeout <seconds> | Request timeout in seconds (default: 10) | | -f, --file <path> | Run a single .req or .request file | | -V, --verbose | Show request and response for each test (method, URL, headers, body, status, response body) | | --var <key=value> | Override a variable (e.g. BASE_URL=https://api.example.com); can be repeated |

HTTP 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: {workspace}/.{baseFolder}/http/{environmentsFolder}/ (e.g. .cursor/http/.environments/), with files like .env.dev, .env, etc.

HTTP Request File Format

Same as in the CursorToys extension:

• REST Client: METHOD URL then optional headers and body; multiple requests separated by ### (only the first is run in this first version).
• Variables: # @var VAR_NAME=value (or VAR_NAME value); # @env name to select environment.
• Substitution: {{VAR_NAME}} in URL, headers, and body; resolved first from file # @var, then from .env.{name} (or .env) in the environments folder.
• Delay: # @delay(milliseconds) to add a delay before executing the request block. Useful for rate limiting or waiting for async operations.

Example:

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

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

###

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

{
  "name": "John Doe",
  "email": "[email protected]"
}

HTTP Verbose Mode and Overrides

• Verbose (-V / --verbose): prints for each test the request (method, URL, headers, body) and the response (status, body), so you can inspect what was sent and received.
• Environment (-e / --env): chooses which environment to use (e.g. .env.qa). If you pass -e qa, the file’s # @env (if any) is ignored and qa is used.
• Variable overrides (--var KEY=value): overrides variables for the run. You can pass multiple: --var BASE_URL=https://api.example.com --var API_KEY=secret. These override both # @var in the file and values from .env.*.

Examples:

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

Skill Management

Create and manage AI agent skills for Cursor AI.

Create a new skill

cursortoys skill add my-skill

Create with description

cursortoys skill add http-testing -d "Skill for testing HTTP APIs"

Create project-specific skill

cursortoys skill add api-docs -t project -p /path/to/project

Skill Options

| Option | Description | |-------|-------------| | -d, --description <text> | Skill description | | -t, --target <type> | Target directory (personal or project, default: personal) | | -p, --project <dir> | Project directory (required if target is project) | | --base-folder <name> | Base folder name (default: cursor, or CURSORTOYS_BASE_FOLDER) |

Skill Paths

• Personal skills: ~/.cursor/skills/{skill-name}/SKILL.md
• Project skills: {project}/.cursor/skills/{skill-name}/SKILL.md

The command creates a SKILL.md file with a template that you can customize.

LLM Instructions

Display instructions for LLMs on how to use the CLI:

cursortoys --llm

This shows comprehensive documentation about all commands, options, and usage patterns, formatted for LLMs to understand and use the CLI effectively.

HTTP Test Output (Jest/Vitest style)

The CLI uses a visual style similar to Jest/Vitest: checkmarks for pass, crosses for fail, and a short summary with duration.

Example when all tests pass:

  ✓ .cursor/http/health.req 200 OK
  ✓ .cursor/http/users.req 201 Created

Tests: 2 passed, 2 total
Time: 1.23s

Example when some tests fail:

  ✓ .cursor/http/health.req 200 OK
  ✗ .cursor/http/users.req 404 Not Found
    Failed to parse HTTP request (check METHOD URL and format)

Tests: 1 passed, 1 failed, 2 total
Time: 2.45s

Example when using -f and the file is not found:

 FAIL No file found at: /path/to/missing.req

Tests: 0 total
Time: 0.01s

Example with --verbose (request and response shown):

  ✓ .cursor/http/health.req 200 OK
    Request: GET https://api.example.com/health
    Response: 200 OK
    Body: {"status":"ok"}

Tests: 1 passed, 1 total
Time: 0.45s

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

Environment Variables

• CURSORTOYS_BASE_FOLDER: Default base folder (default: cursor)
• CURSORTOYS_ENVIRONMENTS_FOLDER: Environments subfolder (default: .environments)

Integration with CursorToys Extension

The CLI uses the same format and conventions as the CursorToys VS Code extension:

• Same .req / .request file format
• Same environment variable resolution
• Same base folder configuration
• Skills are compatible with Cursor AI Agent Skills

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT