talkie 0.2.1

A command line HTTP client that is easy to use

Talkie

A convenient command-line HTTP client for interacting with APIs and web services. Talkie makes working with HTTP in the terminal simple and human-friendly thanks to intuitive syntax and beautiful formatted output.

Quick Start

# Install
pip install talkie

# Make your first request
talkie get https://jsonplaceholder.typicode.com/posts/1

📺 See demo output

$ talkie get https://jsonplaceholder.typicode.com/posts/1

HTTP/1.1 200 OK
Content-Type: application/json

{
  "userId": 1,
  "id": 1,
  "title": "sunt aut facere repellat provident occasi...",
  "body": "quia et suscipit\nsuscipit recusandae consequuntur..."
}

Contents

• Quick Start
• Features
• Why Talkie?
• Comparison with Alternatives
• Installation
• Usage
  • Basic Requests
  • Headers and Parameters
  • Output and Formatting
  • Curl Command Generation
  • OpenAPI Inspection
  • File Formatting
  • WebSocket
  • GraphQL Requests
  • Request History
• Configuration Management
  • Configuration File
  • Environment Management
  • Configuration Examples
• Development
  • Requirements
  • Project Structure
  • Running Tests
  • Pre-commit Hooks
  • Documentation Site
  • API Documentation
• FAQ
• Troubleshooting
• License
• Contributing

Features

• 🚀 Intuitive syntax for working with HTTP requests
• 🌈 Beautiful colored output with syntax highlighting
• 💡 Automatic content type detection (JSON, XML, HTML)
• 🔍 OpenAPI specification inspection for convenient API work
• 🔄 Curl command generation for compatibility
• 📝 Automatic data formatting (JSON, XML, HTML, Markdown)
• 🌐 Environment support for working with different APIs
• 🔐 Save and reuse headers and tokens
• 💾 Save responses to files
• 🧰 Full support for all HTTP methods
• 🌐 WebSocket connections for bidirectional communication
• 📊 GraphQL requests for working with GraphQL APIs
• 📜 Request history for reuse and analysis
• ⚡ Parallel request execution for improved performance

Why Talkie?

Talkie combines the best of both worlds: the simplicity of HTTPie and the power of curl, while adding features that neither offers out of the box.

When to choose Talkie over HTTPie:

• You need GraphQL — Talkie has a dedicated graphql command with query files and variables
• You work with WebSocket — built-in ws command, no extra tools
• You explore OpenAPI specs — inspect endpoints, schemas, and generate examples
• You run parallel requests — batch API calls with configurable concurrency
• You want searchable history — find, repeat, and export past requests

When to choose Talkie over curl:

• You prefer human-friendly syntax — talkie post /users name=John or -F name=John instead of raw -d
• You want colored, formatted output — JSON/XML/HTML with syntax highlighting
• You need environments — switch between dev/staging/prod with one config
• You don't want to remember curl flags — intuitive -H, -q, -o options

Unique Features

Feature	Description
GraphQL	Native talkie graphql with query files, variables, and introspection
WebSocket	talkie ws for real-time connections, no separate client needed
OpenAPI	Inspect specs, list endpoints, generate request examples
Parallel requests	talkie parallel for batch execution with concurrency control
Request history	Search, repeat, export/import — full audit trail of your API work

Comparison with Alternatives

Feature	Talkie	HTTPie	curl	wget
Intuitive syntax	✅	✅	❌	⚠️
Colored output	✅	✅	❌	❌
JSON/XML formatting	✅	✅	❌	❌
GraphQL	✅	❌	⚠️	❌
WebSocket	✅	❌	✅	❌
OpenAPI inspection	✅	❌	❌	❌
Parallel requests	✅	❌	❌	⚠️
Request history	✅	⚠️	❌	❌
Environment config	✅	⚠️	❌	❌
Curl command generation	✅	⚠️	—	—
Pre-installed	❌	❌	✅	✅
Python API	✅	✅	❌	❌

Legend: ✅ Yes | ⚠️ Partial/Manual | ❌ No | — N/A

Installation

From PyPI

pip install talkie

This also installs the http console script: http GET https://example.com is translated to talkie get … (HTTPie-style verb first).

From source code

git clone https://github.com/craxti/talkie.git
cd talkie
pip install -e .

Usage

Basic Requests

# GET request
talkie get https://api.example.com/users

# POST request with JSON body (httpie-style: after URL use key=value / key:=json, or -F)
talkie post https://api.example.com/users name=John age:=30 is_admin:=true
# same with explicit -F:
talkie post https://api.example.com/users -F name=John -F age:=30 -F is_admin:=true

# PUT request
talkie put https://api.example.com/users/1 -F name=Peter
talkie put https://api.example.com/users/1 name=Peter

# DELETE request
talkie delete https://api.example.com/users/1

Headers and Parameters

# Adding headers
talkie get https://api.example.com/users \
  -H "Authorization: Bearer token123" \
  -H "Accept: application/json"

# Query parameters
talkie get https://api.example.com/users -q "page=1" -q "limit=10"

# Save response to file
talkie get https://api.example.com/users -o users.json

Output and Formatting

# Verbose output
talkie get https://api.example.com/users -v

# JSON only
talkie get https://api.example.com/users --json

# Headers only
talkie get https://api.example.com/users --headers

# Response formatting
talkie get https://api.example.com/users --format json
talkie get https://api.example.com/users -f xml

Curl Command Generation

# Generate curl command for request
talkie curl https://api.example.com/users -H "Authorization: Bearer token123"

# Add curl command to regular request
talkie get https://api.example.com/users --curl

# Build curl with method, headers, and query (no network)
talkie curl https://api.example.com/users -X POST -H "Content-Type: application/json" -q page=1

# Run a pasted curl one-liner
talkie from-curl 'curl -s https://httpbin.org/get'

# Guided tour (GET + pretty output + history)
talkie demo

OpenAPI Inspection

# Inspect OpenAPI specification from URL
talkie openapi https://api.example.com/openapi.json

# Inspect local specification file
talkie openapi ./openapi.yaml

# Show only endpoints
talkie openapi https://api.example.com/openapi.json --endpoints

# Generate request examples
talkie openapi https://api.example.com/openapi.json --examples

File Formatting

# Format JSON file
talkie format data.json

# Format and save to file
talkie format data.json -o formatted.json

# Format with specific type
talkie format data.txt -t json

WebSocket

# Connect to WebSocket server
talkie ws wss://echo.websocket.org

# Send message
talkie ws wss://echo.websocket.org --send "Hello"

# Connect with headers
talkie ws wss://api.example.com/ws \
  -H "Authorization: Bearer token123"

GraphQL Requests

# Simple query
talkie graphql https://api.example.com/graphql \
  -q "query { users { id name } }"

# Query from file
talkie graphql https://api.example.com/graphql -f query.graphql

# Query with variables
talkie graphql https://api.example.com/graphql \
  -f query.graphql -v id=123 -v limit=10

Request History

# Show history
talkie history list

# Show last 10 requests
talkie history list --limit 10

# Search history
talkie history search --method GET --url users

# Repeat request from history
talkie history repeat 1a2b3c4d

# Search in history
talkie history search --method GET --url users

# Export history to file
talkie history export history.json

# Import history from file
talkie history import history.json

# Clear all history
talkie history clear --yes

# Advanced search (time range, status band, host)
talkie history search --domain api.example.com --status-min 400 --status-max 599 --sort desc

# Optional SQLite store (better for very large history)
# export TALKIE_HISTORY_BACKEND=sqlite
# export TALKIE_HISTORY_FILE=~/.talkie/history.sqlite

Parallel Request Execution

# Execute requests from file
talkie parallel -f requests.txt

# File with requests (requests.txt) has format:
# GET https://api.example.com/users/1
# GET https://api.example.com/users/2
# POST https://api.example.com/users -F name=John
# POST https://api.example.com/users name=John age:=30

# Execute multiple requests with parallelism limit
talkie parallel -f requests.txt --concurrency 5

# Use delay between requests
talkie parallel -f requests.txt --delay 0.5

# Save results to separate files
talkie parallel -f requests.txt --output-dir ./results

# Execute multiple requests to one URL
talkie parallel -X GET -u "/users/1" -u "/users/2" -u "/posts/1" -b "https://api.example.com"

Configuration Management

Configuration File

Talkie uses ~/.talkie/config.json file for storing settings. The file is created automatically on first run.

You can create the file manually:

mkdir -p ~/.talkie
cat > ~/.talkie/config.json << EOF
{
  "default_headers": {
    "User-Agent": "Talkie/0.2.1",
    "Accept": "application/json"
  },
  "environments": {
    "dev": {
      "name": "dev",
      "base_url": "https://dev-api.example.com",
      "default_headers": {
        "Authorization": "Bearer dev-token"
      }
    },
    "prod": {
      "name": "prod",
      "base_url": "https://prod-api.example.com",
      "default_headers": {
        "Authorization": "Bearer prod-token"
      }
    }
  },
  "active_environment": "dev"
}
EOF

Configuration file location can be changed using TALKIE_CONFIG_DIR environment variable.

Environment Management

Environments allow storing settings for different APIs and quickly switching between them.

Example of using environment:

# Using base URL from active environment
talkie get /users

# Equivalent to (if active environment is dev)
talkie get https://dev-api.example.com/users

Configuration Examples

Multiple Headers for All Requests

{
  "default_headers": {
    "User-Agent": "Talkie/0.2.1",
    "Accept": "application/json",
    "X-API-Key": "your-api-key"
  }
}

Multiple Environment Setup

{
  "environments": {
    "github": {
      "name": "github",
      "base_url": "https://api.github.com",
      "default_headers": {
        "Authorization": "token ghp_xxxxxxxxxxxx"
      }
    },
    "gitlab": {
      "name": "gitlab",
      "base_url": "https://gitlab.com/api/v4",
      "default_headers": {
        "PRIVATE-TOKEN": "glpat-xxxxxxxxxxxx"
      }
    }
  },
  "active_environment": "github"
}

Development

Requirements

• Python 3.8+
• httpx
• typer
• rich
• pydantic
• pyyaml
• openapi-spec-validator
• pygments
• xmltodict
• html2text
• websockets

Project Structure

talkie/
├── __init__.py          # Package
├── __main__.py          # Entry point
├── cli/                 # Command line interface
│   ├── __init__.py
│   └── main.py          # Command definitions
├── core/                # Application core
│   ├── __init__.py
│   ├── client.py        # HTTP client
│   ├── request_builder.py
│   ├── response_formatter.py
│   └── websocket_client.py  # WebSocket client
└── utils/               # Helper modules
    ├── __init__.py
    ├── config.py        # Configuration management
    ├── formatter.py     # Data formatting
    ├── curl_generator.py
    ├── openapi.py
    ├── graphql.py       # GraphQL support
    ├── history.py       # Request history
    ├── colors.py
    └── logger.py

Running Tests

# Install development dependencies
pip install -e ".[dev]"

# Run all tests
pytest

# Run tests for specific module
pytest tests/test_formatter.py

# Run with coverage
pytest --cov=talkie

Pre-commit Hooks

pip install pre-commit
pre-commit install
# Hooks run automatically on git commit (black, isort, mypy)

Documentation Site

pip install -e ".[dev]"
mkdocs serve
# Open http://127.0.0.1:8000

API Documentation

Documentation is available in the docs/ folder and via mkdocs serve:

• CLI Reference — Complete command-line options
• API Reference — Python API
• Architecture — System design
• Development Setup — Dev environment
• Development Tools — Pre-commit, pytest, etc.

It contains detailed description of all Talkie API components:

• HTTP client and request builder
• WebSocket client
• Utilities for formatting and working with various formats
• GraphQL request interface
• Components for storing and managing request history

FAQ

How to save response to file?

Use -o or --output option:

talkie get https://api.example.com/data -o response.json

How to use OAuth token?

Add Authorization header:

talkie get https://api.example.com/profile -H "Authorization: Bearer YOUR_TOKEN"

Or save it in configuration:

{
  "environments": {
    "myapi": {
      "base_url": "https://api.example.com",
      "default_headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  },
  "active_environment": "myapi"
}

How to work with WebSocket in async scenarios?

Talkie provides Python API for working with WebSocket:

import asyncio
from talkie.core.websocket_client import WebSocketClient

async def main():
    client = WebSocketClient("wss://echo.websocket.org")
    await client.connect()
    await client.send("Hello")
    response = await client.receive()
    print(f"Received: {response.data}")
    await client.disconnect()

asyncio.run(main())

How to execute complex GraphQL query?

Save query to file and pass it to command:

talkie graphql https://api.example.com/graphql -f complex_query.graphql -v id=123 -v limit=10

Troubleshooting

SSL certificate verification failed

If you get SSLError or certificate errors when connecting to HTTPS:

# For development only — disable SSL verification (not recommended for production)
talkie get https://api.example.com --insecure

Command not found: talkie

Ensure Talkie is installed and in your PATH:

pip install talkie
# Or with user install:
pip install --user talkie
# Verify:
which talkie

Colors not displaying in terminal

Some terminals don't support colors. Try:

# Force colored output
export FORCE_COLOR=1
talkie get https://api.example.com/users

# Or disable colors
talkie get https://api.example.com/users --no-color

Config file not found

Talkie uses ~/.talkie/config.json by default. Override with:

export TALKIE_CONFIG_DIR=/path/to/your/config
talkie get /users

Timeout errors

Increase timeout for slow APIs:

talkie get https://api.example.com/slow-endpoint --timeout 60

License

MIT

Contributing

Contributions are welcome! Please create issues and pull requests on GitHub.

1. Fork the repository
2. Create a branch with your changes
3. Submit a pull request

Code guidelines:

• Use black for code formatting
• Add type hints
• Write tests for new functionality