Installation

This page covers every detail of the Cursorist CLI setup. If you have not read the Quick Start yet, start there for the condensed version.

Prerequisites

Before installing the CLI, make sure you have:

• Node.js 18 or newer — check with node --version
• npm — comes with Node.js
• A GitHub account — used for authentication
• Cursor IDE — download here if you do not have it

Install the CLI

Install globally so cursorist is available everywhere:

npm install -g cursorist

Alternatively, run commands without a global install using npx:

npx cursorist <command>

Verify the installation:

cursorist --version

Authenticate

Cursorist uses GitHub OAuth. Run:

cursorist login

A browser window opens for GitHub authorization. After you approve, your tokens are stored locally:

~/.cursorist/config.json

Never commit this file. It contains your access token and refresh token.

To check your current auth status, org defaults, and plugin mode:

cursorist status

Scaffold a Plugin

Navigate to your project root and run:

cursorist plugin init

The interactive wizard walks you through:

1. Select an organization — must already exist on cursor.ist
2. Select a team — within that organization
3. Name your plugin — e.g. acme-frontend-starter
4. Choose components — rules, skills, commands, MCP (pick any combination)

What Gets Created

Only directories for components you selected are created.

Validate Before Deploying

Always validate your plugin structure before publishing:

cursorist plugin validate

This checks:

• Manifest exists and has name, version, description
• At least one component is declared
• Asset files exist in the declared directories

See Validate for all validation rules and error messages.

Deploy

When you are ready to publish:

cursorist plugin deploy --org myorg --team frontend --plugin my-starter

Common options:

See Deploy Workflow for the full step-by-step.

Global Config

All CLI state is stored at ~/.cursorist/config.json:

{
  "default_org": "acme",
  "default_team": "engineering",
  "default_plugin": "acme-engineering-starter",
  "plugin_mode": true
}

When default_org and default_team are set, you can omit --org and --team flags from most commands.

Troubleshooting

command not found: cursorist — Ensure your npm global bin directory is in your PATH. Run npm bin -g to find it.

Login fails or times out — Check your browser for a pending GitHub authorization prompt. Try cursorist login again.

Validation errors — Run cursorist plugin validate and follow the suggestions. See Validate for detailed error explanations.

Next Steps

• CLI Reference — All commands with examples
• Plugin Architecture — How plugins are structured and versioned
• Integration — Set up deeplinks and MCP for one-click installs