pi-super-curl

A pi coding agent extension for API testing with an interactive TUI.

https://github.com/user-attachments/assets/612542b1-5fd0-4cd5-a02e-9384cab9cc98

Two Modes

| Mode | Purpose | |------|---------| | Default | Simple Postman client — manually fill URL, method, headers, body | | Template | Pre-configured requests — just fill a few input fields |

Press Ctrl+T to switch between modes.

Install

pi install npm:pi-super-curl

Quick Start

1. Create config file

Create .pi-super-curl/config.json in your project:

{
  "defaults": {
    "baseUrl": "$API_BASE_URL",
    "envFile": ".env",
    "headers": {
      "Content-Type": "application/json"
    }
  },
  "templates": [
    {
      "name": "create-user",
      "description": "Create a new user",
      "url": "/api/users",
      "method": "POST",
      "auth": {
        "type": "bearer",
        "token": "$API_TOKEN"
      },
      "body": {
        "name": "",
        "email": ""
      },
      "fields": [
        { "name": "name", "label": "Name", "path": "name" },
        { "name": "email", "label": "Email", "path": "email" }
      ]
    }
  ]
}

2. Create .env file

API_BASE_URL=http://localhost:3000
API_TOKEN=your-token-here

3. Run /scurl

Commands

| Command | Description | |---------|-------------| | /scurl | Open request builder | | /scurl-history | Browse and replay past requests | | /scurl-log | Capture logs after request (requires customLogging) |

Keybindings

| Key | Action | |-----|--------| | Tab | Navigate fields | | ↑↓ | Change selection / scroll | | Enter | Send request | | Ctrl+T | Switch Default/Template mode | | Ctrl+U | Import from cURL command | | Esc | Cancel |

Configuration

Structure Overview

{
  "defaults": { ... },      // Settings for Default mode (simple Postman)
  "templates": [ ... ],     // Pre-configured requests for Template mode
  "customLogging": { ... }  // Optional: log capture for debugging
}

defaults — Simple Postman Mode

Settings used when you manually build requests in Default mode:

{
  "defaults": {
    "baseUrl": "$API_BASE_URL",
    "timeout": 30000,
    "envFile": ".env",
    "headers": {
      "Content-Type": "application/json"
    },
    "auth": {
      "type": "bearer",
      "token": "$API_TOKEN"
    }
  }
}

| Field | Description | |-------|-------------| | baseUrl | Prepended to relative URLs | | timeout | Request timeout in ms (default: 30000) | | envFile | Path to .env file | | headers | Default headers for all requests | | auth | Default authentication |

templates — Pre-configured Requests

Each template is self-contained with its own URL, auth, headers, etc:

{
  "templates": [
    {
      "name": "get-user",
      "description": "Get user by ID",
      "baseUrl": "$API_BASE_URL",
      "url": "/api/users/{{env.USER_ID}}",
      "method": "GET",
      "auth": {
        "type": "bearer",
        "token": "$API_TOKEN"
      }
    },
    {
      "name": "create-post",
      "description": "Create a blog post",
      "url": "/api/posts",
      "method": "POST",
      "headers": {
        "X-Custom-Header": "value"
      },
      "body": {
        "title": "",
        "content": "",
        "author_id": "{{env.USER_ID}}"
      },
      "fields": [
        { "name": "title", "label": "Title", "path": "title" },
        { "name": "content", "label": "Content", "path": "content" }
      ]
    }
  ]
}

Template Fields

| Field | Description | |-------|-------------| | name | Template identifier | | description | Shown in UI selector | | baseUrl | Optional, overrides defaults.baseUrl | | url | Endpoint path (supports template variables) | | method | HTTP method (GET, POST, PUT, PATCH, DELETE) | | stream | Enable SSE streaming | | auth | Template-specific auth config | | headers | Template-specific headers | | body | Request body template | | fields | User input fields | | appendField | Auto-add "Additional Instructions" field |

Input Fields

Define what users fill in:

{
  "fields": [
    {
      "name": "prompt",
      "label": "Your prompt",
      "path": "data.message",
      "hint": "→ data.message",
      "default": "Hello",
      "required": true
    }
  ]
}

| Field | Description | |-------|-------------| | name | Field identifier | | label | Display label | | path | JSON path where value is injected (e.g., data.message) | | hint | Optional hint shown in UI | | default | Default value | | required | Whether field is required | | sendToAgent | If true, value goes to pi agent instead of HTTP body |

Authentication Types

// Bearer token
{ "auth": { "type": "bearer", "token": "$API_TOKEN" } }

// API key (custom header)
{ "auth": { "type": "api-key", "token": "$API_KEY", "header": "X-API-Key" } }

// Basic auth
{ "auth": { "type": "basic", "username": "$USER", "password": "$PASS" } }

// JWT (auto-generated per request)
{
  "auth": {
    "type": "jwt",
    "secret": "$JWT_SECRET",
    "algorithm": "HS256",
    "expiresIn": 3600,
    "payload": {
      "user_id": "{{env.USER_ID}}",
      "role": "authenticated"
    }
  }
}

Template Variables

Use anywhere in URLs, headers, body:

| Variable | Description | |----------|-------------| | {{uuid}} | Random UUID v4 | | {{uuidv7}} | Time-ordered UUID v7 | | {{timestamp}} | Unix timestamp (seconds) | | {{timestamp_ms}} | Unix timestamp (ms) | | {{date}} | ISO date string | | {{env.VAR}} or {{$VAR}} | Environment variable |

Note: Use $VAR syntax for top-level config fields (baseUrl, auth.token, auth.secret).
Use {{env.VAR}} syntax inside URLs, headers, body, and JWT payloads.

Custom Logging

Capture server logs after requests for debugging:

{
  "customLogging": {
    "enabled": true,
    "outputDir": "~/Desktop/api-logs",
    "logs": {
      "backend": "/tmp/server.log",
      "app": "logs/app.log"
    },
    "postScript": "process-logs.js"
  }
}

Run /scurl-log after a request to save timestamped logs.

Example: Full Config

{
  "defaults": {
    "baseUrl": "$API_BASE_URL",
    "envFile": ".env",
    "timeout": 30000,
    "headers": {
      "Content-Type": "application/json"
    }
  },
  "templates": [
    {
      "name": "health-check",
      "description": "Check API health",
      "url": "/health",
      "method": "GET"
    },
    {
      "name": "login",
      "description": "Authenticate user",
      "url": "/api/auth/login",
      "method": "POST",
      "body": {
        "email": "",
        "password": ""
      },
      "fields": [
        { "name": "email", "label": "Email", "path": "email" },
        { "name": "password", "label": "Password", "path": "password" }
      ]
    },
    {
      "name": "create-item",
      "description": "Create new item",
      "url": "/api/items",
      "method": "POST",
      "auth": {
        "type": "bearer",
        "token": "$API_TOKEN"
      },
      "body": {
        "id": "{{uuidv7}}",
        "name": "",
        "created_at": "{{date}}"
      },
      "fields": [
        { "name": "name", "label": "Item name", "path": "name" }
      ]
    }
  ],
  "customLogging": {
    "enabled": true,
    "outputDir": "~/Desktop/api-logs",
    "logs": {
      "server": "/tmp/server.log"
    }
  }
}

License

MIT