Saffron 🦀

Saffron is a fast, lightweight command-line HTTP client written in Rust. Test APIs, debug endpoints, and manage request collections — all from your terminal.

✨ Features

• 🚀 Fast & Lightweight: Single binary, minimal dependencies, <5MB
• 📦 Collections: Organize requests into reusable collections
• 🔄 Import from External Tools: Import collections from Insomnia (Postman coming soon)
• 🌍 Environments: Manage variables across dev/staging/production
• 📜 Request History: Automatic tracking with 100-entry rolling cache
• 🔧 Template Variables: Use {{variables}} in URLs, headers, and body
• 🎨 Colored Output: Beautiful, readable terminal responses
• 💾 Persistent Storage: All data stored locally in ~/.saffron/
• 🔒 Privacy-First: No cloud sync, everything runs locally
• ⚡ Zero Configuration: Works out of the box

🚀 Quick Start

Installation

From source:

git clone https://github.com/yourusername/saffron.git
cd saffron
cargo build --release

The binary will be in target/release/saffron.exe.

From crates.io (coming soon):

cargo install saffron

Your First Request

# Simple GET request
saffron send https://api.github.com

# POST with JSON
saffron send https://api.example.com/users `
  --method POST `
  --header "Content-Type: application/json" `
  --body '{"name": "Alice", "email": "alice@example.com"}'

# Using environment variables
saffron env set production api_url https://api.prod.com
saffron send {{api_url}}/users

📚 Documentation

• Getting Started - Installation, configuration, basic usage
• CLI Reference - Complete command reference
• Examples - Real-world usage patterns
• Architecture - Technical design and structure
• Contributing - How to contribute
• FAQ - Frequently asked questions

💡 Core Concepts

Collections

Organize related requests:

# Create collection
saffron collection new github-api

# Add request
saffron collection add github-api get-user `
  --method GET `
  --url https://api.github.com/users/octocat

# Run request from collection
saffron send --from-collection "github-api/get-user"

# Import from Insomnia
saffron collection import insomnia-export.json

# List all collections
saffron collection list

Environments

Manage variables across environments:

# Set variables
saffron env set development base_url https://api.dev.com
saffron env set production base_url https://api.prod.com

# Switch environments
saffron env use production

# Use in requests
saffron send {{base_url}}/users

Request History

Automatic tracking of all requests:

# List history
saffron history list

# Show details
saffron history show abc123

# Rerun a request
saffron history rerun abc123

# Clear history
saffron history clear

🎯 Why Saffron?

🏗️ Architecture

Saffron is built as a modular Rust workspace:

saffron/
├── saffron-core     # Domain models (requests, responses, collections)
├── saffron-http     # HTTP client implementation (ureq-based)
├── saffron-data     # Custom JSON parser (no external deps)
├── saffron-cli      # Command-line interface (clap-based)
├── saffron-ui       # GUI (planned)
└── saffron-utils    # Shared utilities

See Architecture for details.

🧪 Testing

Saffron has comprehensive test coverage:

# Run all tests
cargo test

# Run specific crate tests
cargo test -p saffron-core
cargo test -p saffron-http
cargo test -p saffron-data

Current test counts:

• saffron-core: 82 tests
• saffron-data: 33 tests
• saffron-http: 18 tests
• Total: 133 tests

🗺️ Roadmap

✅ Completed (v0.1.0)

• Core HTTP client
• CLI interface
• Collections management
• Environment variables
• Request history
• Template variable resolution
• Colored terminal output
• Comprehensive documentation

🚧 In Progress

• GUI implementation (saffron-ui)
• Import/export (Postman, Insomnia)
• SSL verification control
• Proxy support

📋 Planned

• GraphQL support
• WebSocket support
• Request chaining
• Response assertions
• Pre/post-request scripts
• Code generation (curl, Python, etc.)
• Team sync (Git-based)

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

Quick checklist:

• Fork the repository
• Create a feature branch
• Write tests
• Follow coding standards
• Submit a pull request

📝 License

Saffron is licensed under the MIT License.

🙏 Acknowledgments

Built with these excellent Rust crates:

• ureq - HTTP client
• clap - CLI parsing
• serde - Serialization
• colored - Terminal colors
• thiserror - Error handling

📧 Contact

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Made with ❤️ and Rust