Creating Plot Twists
    Preparing search index...

    CLI Reference

    Complete reference for the Plot CLI (plot command).

    The Plot CLI is included with the Builder:

    # Run directly with npx
    npx @plotday/twister [command]

    # Or install globally
    npm install -g @plotday/twister
    plot [command]

    Authenticate with Plot to generate an API token.

    plot login

    This will:

    1. Open your browser to the Plot authentication page
    2. After authentication, save your API token locally
    3. Enable deploying and managing twists

    Token Storage: The token is stored in ~/.plot/config.json

    Scaffold a new twist project with TypeScript.

    plot create [options]

    Options:

    • --name <name> - Package name (kebab-case)
    • --display-name <name> - Human-readable display name
    • --dir <directory> - Output directory (default: current directory)

    Example:

    plot create --name my-calendar-twist --display-name "My Calendar twist"

    Creates:

    my-calendar-twist/
    ├── src/
    │   └── index.ts
    ├── package.json
    ├── tsconfig.json
    └── plot-twist.json

    Generate TypeScript code from a natural language plot-twist.md specification.

    plot generate [options]

    Options:

    • --input <path> - Path to plot-twist.md (default: ./plot-twist.md)
    • --output <directory> - Output directory (default: ./src)
    • --overwrite - Overwrite existing files

    Example:

    plot generate --input ./my-spec.md --output ./src

    Check twist code for errors without deploying.

    plot lint [options]

    Options:

    • --dir <directory> - twist directory (default: current directory)

    Example:

    plot lint --dir ./my-twist

    Deploy an twist to Plot.

    plot deploy [options]

    Options:

    • --twist-id <id> - Update existing twist (creates new if not specified)
    • --name <name> - twist name
    • --description <description> - twist description
    • --source <path> - Source directory (default: ./src)
    • --env <environment> - Environment (default: production)
    • --dry-run - Validate without deploying

    Behavior:

    • If plot-twist.md exists: Generates code and deploys in one step
    • Otherwise: Deploys compiled TypeScript from src/

    Example:

    # Deploy new twist
    plot deploy

    # Update existing twist
    plot deploy --twist-id ag_1234567890

    # Dry run
    plot deploy --dry-run

    Stream real-time logs from an twist.

    plot logs [twist-id] [options]

    Options:

    • --id <twistId> - twist ID
    • --dir <directory> - twist directory (default: current directory)
    • --environment <env> - twist environment (personal, private, review) (default: personal)
    • --deploy-token <token> - Authentication token

    Example:

    # Stream logs for an twist
    plot logs ag_1234567890

    # Stream logs using twist in current directory
    plot logs --dir ./my-twist

    List all priorities for the authenticated user.

    plot priority list

    Output:

    pr_0987654321  Work
      pr_1111111111  Project A
      pr_2222222222  Project B
    pr_3333333333  Personal

    Create a new priority.

    plot priority create [options]

    Options:

    • --name <name> - Priority name (required)
    • --parent-id <id> - Parent priority ID (optional)

    Example:

    # Create top-level priority
    plot priority create --name "Work"

    # Create nested priority
    plot priority create --name "Project A" --parent-id pr_0987654321

    These options are available for all commands:

    • --help, -h - Show help for command
    • --version, -v - Show CLI version
    • --verbose - Enable verbose logging
    • --config <path> - Use custom config file (default: ~/.plot/config.json)

    Example:

    plot deploy --verbose
    plot --version

    The CLI stores configuration in ~/.plot/config.json:

    {
      "auth": {
        "token": "your-api-token",
        "userId": "user_1234567890"
      },
      "defaults": {
        "environment": "production"
      }
    }

    Edit the config file to set default options:

    {
      "defaults": {
        "environment": "staging",
        "twistSourceDir": "./dist"
      }
    }

    Configure the CLI using environment variables:

    • PLOT_API_TOKEN - API authentication token
    • PLOT_API_URL - API endpoint (default: https://api.plot.day)
    • PLOT_CONFIG_PATH - Custom config file path

    Example:

    export PLOT_API_TOKEN=your-token
    plot deploy

    # 1. Create project
    plot create --name my-twist

    # 2. Navigate to directory
    cd my-twist

    # 3. Implement twist
    # Edit src/index.ts

    # 4. Login (if not already authenticated)
    plot login

    # 5. Deploy
    npm run deploy

    # 1. Make changes to src/index.ts

    # 2. Build
    npm run build

    # 3. Deploy update
    plot deploy --twist-id ag_1234567890

    # 1. Create plot-twist.md
    # Describe your twist in plain English

    # 2. Login
    plot login

    # 3. Deploy directly from spec
    plot deploy

    # Clear saved token
    rm ~/.plot/config.json

    # Login again
    plot login

    # Check for TypeScript errors
    npm run build

    # Or use lint command
    plot lint

    # Try dry run first
    plot deploy --dry-run

    # Enable verbose logging
    plot deploy --verbose

    Settings

    Member Visibility

    On This Page

    CLI Reference