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