💅 Pinky - HTTP Client TUI

A beautiful and intuitive terminal-based HTTP client built with TypeScript and Lipgloss.

✨ Features

• 🎨 Beautiful TUI - Powered by Lipgloss for a polished terminal interface with Ocean Breeze theme
• ⌨️ Keyboard Navigation - Fully navigable via keyboard shortcuts
• 📁 Request Groups - Organize your HTTP requests into collections
• 🔍 Full-Text Search - Search across all requests by name, URL, method, or group
• 🚀 Quick Execution - Execute requests and view responses instantly
• 📝 Request Details - View method, URL, headers, query params, and body
• 💾 Persistent Storage - All data saved to ~/.config/pinky
• 🎯 HTTP Methods - Support for GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
• 📊 Response Viewer - View status, headers, body, and timing information
• 🌈 Color Coding - Different colors for HTTP methods and status codes
• 📦 Demo Data - Includes sample requests for JSONPlaceholder and GitHub APIs
• 📜 Request History - Track and view recent request executions (last 100)
• 📋 Copy as cURL - One-key copy of requests as cURL commands
• 🌍 Environment Variables - Support for {{variable}} substitution in requests

🖼️ Screenshots

Groups View

╭────────────────────────────────────────────────────────────────────────────────────╮
│  💅 Pinky HTTP Client | Groups                                                     │
│                                                                                    │
│  Groups:                                                                           │
│                                                                                    │
│  ▶ JSONPlaceholder API (5 requests)                                                │
│    GitHub API (2 requests)                                                         │
│                                                                                    │
│  ↑/↓ Navigate  Enter Select  n New Group  d Delete  q Quit  ? Help                 │
╰────────────────────────────────────────────────────────────────────────────────────╯

Requests View

╭────────────────────────────────────────────────────────────────────────────────────╮
│  💅 Pinky HTTP Client | Requests | JSONPlaceholder API                             │
│                                                                                    │
│  Requests in JSONPlaceholder API:                                                  │
│                                                                                    │
│  ▶ GET     Get All Posts                                                           │
│           https://jsonplaceholder.typicode.com/posts                               │
│    POST    Create Post                                                             │
│    PUT     Update Post                                                             │
│    DELETE  Delete Post                                                             │
│                                                                                    │
│  ↑/↓ Navigate  Enter Execute  e Edit  n New Request  d Delete  Esc Back  q Quit    │
╰────────────────────────────────────────────────────────────────────────────────────╯

Response View

╭────────────────────────────────────────────────────────────────────────────────────╮
│  💅 Pinky HTTP Client | Response                                                   │
│                                                                                    │
│  Response                                                                          │
│                                                                                    │
│  Status: 200 OK                                                                    │
│  Duration: 245ms                                                                   │
│  Time: 11/10/2025, 6:00:00 PM                                                      │
│                                                                                    │
│  Headers:                                                                          │
│    content-type: application/json; charset=utf-8                                   │
│                                                                                    │
│  Body:                                                                             │
│  {                                                                                 │
│    "id": 1,                                                                        │
│    "title": "Test Post"                                                            │
│  }                                                                                 │
│                                                                                    │
│  Esc Back  r Re-execute  q Quit                                                    │
╰────────────────────────────────────────────────────────────────────────────────────╯

🚀 Installation

Global Installation (Recommended)

Install Pinky globally using npm:

npm install -g @urbanisierung/pinky

Or using pnpm:

pnpm add -g @urbanisierung/pinky

Or using yarn:

yarn global add @urbanisierung/pinky

Once installed, you can run Pinky from anywhere:

pinky

From Source

# Clone the repository
git clone https://github.com/urbanisierung/lipgloss.git
cd lipgloss/apps/pinky

# Install dependencies
pnpm install

# Build the application
pnpm build

# Run the application
pnpm start

# Or run in development mode with hot reload
pnpm dev

📖 Usage

Starting Pinky

# Development mode
cd apps/pinky
pnpm dev

# Or after building
pnpm start

On first run, Pinky creates demo data with example requests to JSONPlaceholder and GitHub APIs. This data is saved to ~/.config/pinky/data.json and will persist between sessions.

Navigation

Groups View

• ↑/↓ - Navigate between groups
• Enter - Open selected group
• n - Create new group
• d - Delete selected group
• / - Search requests
• q - Quit application

Requests View

• ↑/↓ - Navigate between requests
• Enter - Execute selected request
• e - Edit selected request
• n - Create new request
• d - Delete selected request
• Esc - Back to groups
• q - Quit application

Editor View

• Enter - Save changes
• Esc - Cancel editing
• q - Quit application

Response View

• r - Re-execute request
• c - Copy request as cURL command
• Esc - Back to requests
• q - Quit application

Search View

• Type to search across all requests
• ↑/↓ - Navigate search results
• Enter - Select result and jump to request
• Backspace - Delete search character
• Esc - Cancel search
• q - Quit application

History View

• View last 20 executed requests
• Esc - Back to groups
• q - Quit application

Environment Variables View

• View active environment and variables
• Esc - Back to groups
• q - Quit application

Creating and Managing Requests

Pinky currently supports viewing and executing pre-configured requests. To add or modify requests:

1. Via Code: Edit the storage file at ~/.config/pinky/data.json
2. Via API: Use the data models in the codebase to create requests programmatically
3. Interactive Editing: Coming in a future release

Example request structure:

{
  "id": "unique-id",
  "name": "Get Users",
  "method": "GET",
  "url": "https://api.example.com/users",
  "headers": [
    { "key": "Accept", "value": "application/json", "enabled": true }
  ],
  "queryParams": [
    { "key": "page", "value": "1", "enabled": true }
  ],
  "body": "",
  "bodyType": "json",
  "createdAt": "2025-01-01T00:00:00.000Z",
  "updatedAt": "2025-01-01T00:00:00.000Z"
}

Executing a Request

1. Navigate to a group and press Enter to open it
2. Use ↑/↓ to select a request
3. Press Enter to execute the request
4. View the response with status, headers, and body
5. Press r to re-execute or Esc to go back
6. Press c to copy the request as a cURL command

Searching for Requests

1. From the groups view, press / to open search
2. Type your search query (searches name, URL, method, and group)
3. Use ↑/↓ to navigate results
4. Press Enter to select a result and jump to that request
5. Press Esc to cancel search

Viewing Request History

1. From the groups view, press h to open history
2. View recent request executions with status codes and timing
3. History shows the last 20 requests (stores up to 100)
4. Press Esc to go back

Using Environment Variables

Environment variables allow you to use dynamic values in your requests using the {{variable}} syntax.

Setting up environments:

1. Create an environments file at ~/.config/pinky/environments.json:

{
  "environments": [
    {
      "id": "env-1",
      "name": "Development",
      "variables": [
        { "key": "API_URL", "value": "http://localhost:3000", "enabled": true },
        { "key": "API_KEY", "value": "dev-key-123", "enabled": true }
      ]
    },
    {
      "id": "env-2",
      "name": "Production",
      "variables": [
        { "key": "API_URL", "value": "https://api.example.com", "enabled": true },
        { "key": "API_KEY", "value": "prod-key-456", "enabled": true }
      ]
    }
  ],
  "currentEnvironmentId": "env-1",
  "version": "0.2.0"
}

2. Use variables in your requests:

{
  "url": "{{API_URL}}/users",
  "headers": [
    { "key": "Authorization", "value": "Bearer {{API_KEY}}", "enabled": true }
  ]
}

3. Press v from groups view to see active environment and variables
4. Variables are automatically substituted when requests are executed
5. Variables work in URLs, headers, query parameters, and body

Copying Requests as cURL

1. Execute a request
2. From the response view, press c
3. The cURL command is copied to your clipboard (if available)
4. If clipboard copy fails, the command is shown in a message
5. Environment variables are automatically substituted in the cURL command

Request Configuration

Each request can be configured with:

• Name - Descriptive name for the request
• Method - HTTP method (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS)
• URL - Target URL
• Headers - Custom HTTP headers (can be enabled/disabled individually)
• Query Parameters - URL query parameters (can be enabled/disabled individually)
• Body - Request body (for POST, PUT, PATCH)
• Body Type - Text or JSON

Common Use Cases

API Testing

1. Create a group for your API
2. Add requests for each endpoint
3. Configure headers (auth tokens, content-type)
4. Execute and verify responses

Quick HTTP Checks

1. Use demo data as templates
2. Execute GET requests to check API health
3. View response times and status codes

Development Workflow

1. Group requests by feature or service
2. Toggle headers/params for different environments
3. Re-execute requests quickly during development

Storage

All data is automatically saved to ~/.config/pinky/:

• data.json - Groups and requests
• history.json - Request execution history (last 100 entries)
• environments.json - Environment variables and active environment

Data is saved automatically after each change.

🎨 UI Overview

Pinky uses a beautiful TUI layout with:

• Header - Application title and current view
• Content Area - Main content (groups, requests, editor, response)
• Footer - Keyboard shortcuts for current view

Color Coding

• GET - Green
• POST - Yellow
• PUT - Orange
• PATCH - Purple
• DELETE - Red
• HEAD - Cyan
• OPTIONS - Gray

Response Status Colors

• 2xx Success - Green
• 3xx Redirect - Blue
• 4xx Client Error - Red
• 5xx Server Error - Red
• Error - Red

🛠️ Development

Tech Stack

• TypeScript - Type-safe JavaScript (ES2022)
• Node.js - Runtime (v18+)
• @urbanisierung/lipgloss - Terminal UI framework with TUI shell
• Vitest - Fast unit test framework
• Biome - Lightning-fast linting and formatting

Architecture

Pinky follows a clean architecture pattern:

• UI Layer (ui.ts) - Renders TUI using Lipgloss shell
• Application Layer (index.ts) - Main app logic and keyboard handling
• Service Layer (http-client.ts, storage.ts) - Business logic
• Domain Layer (types.ts) - Core data models
• Utilities (utils.ts, demo.ts) - Helper functions

Project Structure

src/
├── index.ts              # Main application entry point
├── types.ts              # TypeScript type definitions
├── storage.ts            # Data persistence service
├── http-client.ts        # HTTP request execution
├── ui.ts                 # UI rendering with Lipgloss
├── utils.ts              # Helper utilities
├── demo.ts               # Demo data generator
└── demo-screenshots.ts   # Screenshot generator for docs

test/
├── storage.test.ts       # Storage tests
├── http-client.test.ts   # HTTP client tests
└── utils.test.ts         # Utility function tests

Running Tests

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run with coverage (coming soon)
pnpm test:coverage

Current test coverage:

• ✅ 19 tests passing
• ✅ Storage service tests
• ✅ HTTP client tests
• ✅ Utility function tests

Linting

pnpm lint

📝 Examples

Example Request

{
  "name": "Get Users",
  "method": "GET",
  "url": "https://jsonplaceholder.typicode.com/users",
  "headers": [
    { "key": "Accept", "value": "application/json", "enabled": true }
  ],
  "queryParams": [],
  "body": "",
  "bodyType": "json"
}

Example Group

{
  "name": "JSONPlaceholder API",
  "requests": [
    { "name": "Get Users", "method": "GET", "url": "https://jsonplaceholder.typicode.com/users" },
    { "name": "Get Posts", "method": "GET", "url": "https://jsonplaceholder.typicode.com/posts" },
    { "name": "Create Post", "method": "POST", "url": "https://jsonplaceholder.typicode.com/posts" }
  ]
}

🔮 Roadmap

v0.2.0 (Planned)

• ✅ Interactive request editing in TUI
• ✅ Full-text search across all requests
• ✅ Request history and recent requests
• ✅ Copy request as cURL command
• ✅ Environment variables support

v0.3.0 (Planned)

• [ ] Import/Export collections (JSON, Postman)
• [ ] Authentication helpers (Basic, Bearer, OAuth)
• [ ] Request chaining and variables
• [ ] Response caching
• [ ] Custom color themes

v1.0.0 (Planned)

• [ ] GraphQL support
• [ ] WebSocket support
• [ ] Request scripts (pre-request, post-request)
• [ ] Team collaboration features
• [ ] Syntax highlighting for JSON/XML

Known Limitations

• Request editing is view-only in the TUI; use the JSON file to modify request details
• Environment switching requires editing the environments.json file manually
• No import/export of collections yet
• History view is read-only (no ability to re-execute from history yet)

🐛 Troubleshooting

App won't start

• Ensure Node.js v18+ is installed
• Run pnpm install to install dependencies
• Check terminal size (minimum 60x20 recommended)

Data not saving

• Ensure write permissions to ~/.config/pinky
• Check disk space availability

Requests failing

• Verify URL is correct and accessible
• Check network connectivity
• Review request headers and body

UI looks broken

• Ensure terminal supports ANSI colors
• Try resizing terminal window
• Use a modern terminal emulator (iTerm2, Windows Terminal, etc.)

🤝 Contributing

Contributions are welcome! Please read the CONTRIBUTING.md in the root repository.

📄 License

MIT - See LICENSE in the root repository.

🙏 Acknowledgments

• Built with Lipgloss
• Inspired by Postman and Insomnia

Made with 💅 by the Lipgloss team