Skip to content

kbrdn1/LazyCurl

BranchesTags

Repository files navigation

LazyCurl Logo
LazyCurl

A powerful Terminal User Interface (TUI) HTTP client
Combining Lazygit's elegant interface with Postman's API testing capabilities

Features • Installation • Quick Start • Shortcuts • Documentation • Contributing

CI Release Coverage Go Report Card CodeRabbit Reviews

Go Version Bubble Tea Catppuccin License

🎯 Philosophy

LazyCurl is designed for developers who live in the terminal. It combines:

  • Elegant Interface — Lazygit's proven multi-panel layout with vim motions
  • Powerful Features — Postman's comprehensive HTTP testing capabilities
  • File-Based Storage — Simple, versionable JSON/YAML files you can commit to git
  • Keyboard-First — Full vim-style navigation, no mouse required

✨ Features

🎨 Lazygit-Style Interface

┌─Collections────────┬─Request──────────────────────────┐
│                    │ POST    {{base_url}}/api/users   │
│ ▼ My API           │──────────────────────────────────│
│   ▶ Users          │ Params │ Auth │ Headers │ Body   │
│     GET  /users    │──────────────────────────────────│
│     POST /users    │ {                                │
│     GET  /users/:id│   "name": "John Doe",            │
│   ▶ Products       │   "email": "{{user_email}}"      │
│                    │ }                                │
│                    ├─Response────────────────────────-┤
│                    │ 201 Created  │ 142ms │ 1.2 KB    │
│                    │──────────────────────────────────│
│                    │ {                                │
│                    │   "id": 123,                     │
│                    │   "name": "John Doe"             │
│                    │ }                                │
└────────────────────┴──────────────────────────────────┘
 NORMAL │ POST │ My API > Users > Create User │ dev │ ?:help

🚀 Core Features

Feature Description
Multi-Panel Layout Collections, Request Builder, Response Viewer in one view
Vim Motions Navigate with h/j/k/l, modes (NORMAL, INSERT, VIEW, COMMAND)
HTTP Methods GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
Collections Organize requests in folders, stored as JSON files
Environments Multiple environments with variable substitution {{var}}
Variable System Environment variables + built-in system variables
Search Filter collections and environments with /
WhichKey Press ? for context-aware keybinding hints
Command Mode Vim-style commands with : prefix
Mouse Support Click to select, scroll to navigate
Session Persistence Automatic save/restore of application state

🔧 Request Builder

  • URL with variable substitution ({{base_url}}/api/users)
  • Headers with key-value editor
  • Body Types: JSON, Form Data, Raw Text, Binary
  • Query Parameters with interactive table
  • Authorization: Bearer Token, API Key, Basic Auth

📊 Response Viewer

  • Formatted Output: JSON syntax highlighting
  • Status Badges: Color-coded (2xx green, 4xx orange, 5xx red)
  • Metadata: Response time, size, headers
  • Tabs: Body, Headers, Cookies, Console

📟 Console (Request History)

  • Request/Response Logging: View chronological history of all HTTP requests made during session
  • Visual Status Indicators: Color-coded badges for 2xx/3xx/4xx/5xx responses and network errors
  • Quick Actions: Resend requests, copy headers/body/error to clipboard
  • Vim Navigation: Browse history with j/k, expand entries with Enter/l

💾 Session Persistence

  • Automatic State Saving: Application state is saved automatically on changes
  • Seamless Restore: Resume exactly where you left off when reopening
  • What's Saved: Active panel, selected request, active environment, expanded folders, scroll positions, active tabs
  • Smart Debouncing: 500ms delay prevents excessive writes during rapid changes
  • Atomic Writes: Safe file operations using temp file + rename pattern
  • Graceful Degradation: Missing or invalid session files are handled silently

🌍 Environment System

{
  "name": "Development",
  "variables": {
    "base_url": { "value": "http://localhost:3000", "active": true },
    "api_token": { "value": "secret-token", "secret": true, "active": true }
  }
}

Built-in System Variables:

  • {{$timestamp}} — Unix timestamp
  • {{$datetime}} — RFC3339 datetime
  • {{$uuid}} — UUID v4
  • {{$randomInt}} — Random integer
  • {{$random}} — Random alphanumeric string

📦 Installation

Prerequisites

  • Go 1.21 or higher
  • Terminal with Unicode support

From Source

# Clone the repository
git clone https://github.com/kbrdn1/LazyCurl.git
cd LazyCurl

# Build
make build

# Run
./bin/lazycurl

# Or install globally
make install

Using Go Install

go install github.com/kbrdn1/LazyCurl/cmd/lazycurl@latest

Development Mode

# Live reload during development
make dev

🚀 Quick Start

1. Initialize a Workspace

cd your-api-project
lazycurl

LazyCurl automatically creates a .lazycurl/ directory:

.lazycurl/
├── config.yaml           # Workspace settings
├── collections/          # Your API collections
│   └── example.json
└── environments/         # Environment files
    └── development.json

2. Create Your First Request

  1. Press n to create a new request
  2. Enter request details (name, method, URL)
  3. Press Enter to confirm
  4. Press Ctrl+S to send the request

3. Use Variables

  1. Press 2 or Tab to switch to Environments tab
  2. Press n to create a variable
  3. Use {{variable_name}} in your URLs and body

⌨️ Keyboard Shortcuts

Vim-Style Modes

Mode Indicator Description
NORMAL NORMAL (blue) Default mode, navigate and execute commands
INSERT INSERT (gray) Text input mode for editing fields
VIEW VIEW (green) Read-only browsing of responses
COMMAND COMMAND (orange) Execute commands with : prefix

Navigation

Key Action
h / l Switch panels (left/right)
j / k Move up/down in lists
g / G Jump to top/bottom
1 / 2 Switch tabs (Collections/Environments)
Tab Next tab in request builder

Collections Panel

Key Action
n New request
N New folder
c / i Edit request
R Rename
d Delete
D Duplicate
y Yank (copy)
p Paste
/ Search
Enter / Space Open request

Environments Panel

Key Action
n New variable
N New environment
c / i Edit value
R Rename
d Delete
D Duplicate
a / A Toggle active
s Toggle secret
S / Enter Select environment
/ Search

Response Panel

Key Action
1 Body tab
2 Cookies tab
3 Headers tab
4 Console tab (request history)
Tab / Shift+Tab Next/previous tab
j / k Scroll content / navigate list
g / G Jump to top/bottom

Console Tab (List View)

Key Action
j / k Navigate up/down in history
g / G Jump to first/last entry
Enter / l Expand selected entry
R Resend selected request
U Copy URL to clipboard

Console Tab (Expanded View)

Key Action
Esc / h / q Collapse back to list
R Resend request
H Copy headers
B Copy body
E Copy error message
C Copy cookies
I Copy request info
A Copy all (request & response)

Search Mode

Key Action
n Next match
N Previous match
i Edit search query
Esc Clear search
Enter / Space Open selected item

Global

Key Action
Ctrl+S Send request
? Show keybinding help (WhichKey)
: Enter command mode
Esc Return to NORMAL mode
q Quit

Command Mode

Command Action
:q Quit
:w Save
:wq Save and quit
:help Show help
:ws list List workspaces

📁 File Structure

Workspace Layout

your-project/
├── .lazycurl/
│   ├── config.yaml              # Workspace configuration
│   ├── session.yml              # Session state (auto-generated)
│   ├── collections/
│   │   ├── api.json             # Collection file
│   │   └── admin.json
│   └── environments/
│       ├── development.json     # Environment file
│       ├── staging.json
│       └── production.json
└── ...

Global Configuration

~/.config/lazycurl/
└── config.yaml                  # Global settings, themes, keybindings

Collection Format

{
  "name": "My API",
  "description": "API collection description",
  "folders": [
    {
      "name": "Users",
      "requests": [
        {
          "id": "req_001",
          "name": "Get All Users",
          "method": "GET",
          "url": "{{base_url}}/api/users",
          "headers": {
            "Authorization": "Bearer {{token}}"
          }
        },
        {
          "id": "req_002",
          "name": "Create User",
          "method": "POST",
          "url": "{{base_url}}/api/users",
          "headers": {
            "Content-Type": "application/json"
          },
          "body": {
            "name": "{{user_name}}",
            "email": "{{user_email}}"
          }
        }
      ]
    }
  ]
}

Environment Format

{
  "name": "Development",
  "description": "Local development environment",
  "variables": {
    "base_url": {
      "value": "http://localhost:3000",
      "active": true
    },
    "token": {
      "value": "dev-secret-token",
      "secret": true,
      "active": true
    },
    "user_name": {
      "value": "Test User",
      "active": true
    }
  }
}

🎨 Theme

LazyCurl uses the Catppuccin Mocha color scheme:

Element Color
Primary (Selection) Lavender #b4befe
Secondary Blue #89b4fa
Success/Active Green #a6e3a1
Warning Peach #fab387
Error Red #f38ba8
Text White #cdd6f4
Background Base #1e1e2e

HTTP Method Colors:

  • GET/HEAD: Green
  • POST: Orange
  • PUT: Blue
  • PATCH: Purple
  • DELETE: Red
  • OPTIONS: Brown

📚 Documentation

Full documentation is available in the docs/ directory:

Document Description
Installation Complete installation guide
Getting Started First steps with LazyCurl
Keybindings Complete keyboard reference
Configuration Config files and options
Collections Managing request collections
Environments Variables and environments
StatusBar StatusBar component and modes
Architecture Technical architecture

🛠️ Development

Make Commands

make build          # Build binary to bin/lazycurl
make run            # Build and run
make dev            # Live reload with air
make test           # Run tests
make test-coverage  # Generate coverage report
make fmt            # Format code
make lint           # Run linter
make clean          # Clean build artifacts
make build-all      # Cross-compile for all platforms

Project Structure

LazyCurl/
├── cmd/lazycurl/           # Application entry point
├── internal/
│   ├── api/                # HTTP client, collections, environments
│   ├── config/             # Configuration management
│   ├── format/             # Response formatting
│   └── ui/                 # User interface
│       ├── components/     # Reusable UI components
│       └── *.go            # Panel implementations
├── pkg/styles/             # Catppuccin theme and styles
├── docs/                   # Documentation
└── Makefile

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

Quick Start

# Fork and clone
git clone https://github.com/YOUR_USERNAME/LazyCurl.git
cd LazyCurl

# Create feature branch
git checkout -b feat/#123-your-feature

# Make changes and commit (using Gitmoji)
git commit -m "✨ feat(ui): add new feature"

# Push and create PR
git push origin feat/#123-your-feature

Commit Convention

We use Gitmoji + Conventional Commits:

✨ feat(scope): add new feature
🐛 fix(scope): fix bug
📝 docs(scope): update documentation
♻️ refactor(scope): refactor code
🎨 style(scope): improve styling
✅ test(scope): add tests

🗺️ Roadmap

✅ Phase 1 - Foundation (Complete)

  • Lazygit-style multi-panel interface
  • Vim-style navigation and modes
  • Workspace system with file-based storage
  • Configuration system (global + workspace)
  • Collections and environments management

🔥 Sprint 1 - MVP (Complete)

  • Collection tree view with folders
  • Environment management with variables
  • Request builder UI
  • Search functionality
  • WhichKey keybinding hints
  • HTTP request execution
  • Response formatting
  • CI/CD pipeline

📋 Sprint 2 - UX Improvements

  • Responsive panel layout (horizontal on 80x24 terminals) #7
  • Fullscreen panel toggle (F in NORMAL mode, h/l to navigate) #8
  • Find in editors (/ in NORMAL mode) #24
  • Settings Panel (Ctrl+; fullscreen with Global/Workspace tabs) #25
  • Console tab in Response Panel (request/response history) #9
  • Improved statusbar rendering and display #10
  • Session persistence (.lazycurl/session.yml) #11
  • Theme system refactoring #12
  • Theme management and custom themes #13

🔮 Future

  • Import/export Postman collections #14
  • Request history #15
  • Pre-request & post-response scripting (JavaScript via Goja) #35
  • Authentication helpers (OAuth2, AWS Sig) #17
  • GraphQL support #18
  • WebSocket testing #19
  • gRPC support #20
  • CLI commands architecture #26

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

LazyCurl is built on the shoulders of giants:

Made with ❤️ by @kbrdn1

⭐ Star us on GitHub

About

A powerful Terminal User Interface (TUI) HTTP client

Topics

go golang postman amnesia bubbletea lazygit lipgloss

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Contributors 3

  •  
  •  
  •  

Languages