Elysium - The API App Store

Version: 1.0.0
Status: Stable

Elysium is an API app store that allows developers and AI agents to discover, download, and use APIs programmatically through defined emblems—YAML files that describe an API's endpoints, parameters, authentication, and types.

The Problem

APIs are everywhere, but using them requires:

• Reading extensive documentation
• Understanding authentication flows
• Writing boilerplate HTTP client code
• Managing API keys and environment variables
• Handling rate limits, errors, and edge cases

The Solution

Emblems are machine-readable API definitions that enable:

• 🤖 AI Agents to use APIs without human intervention
• 👨‍💻 Developers to skip documentation dive
• 🔄 Automation of complex API workflows
• 📦 Version control for API integrations

What's New in v1.0.0

• 🔄 Self-Update — ely self-update updates the CLI binary in place
• 🌐 Browser-Based Auth — device-flow OAuth for seamless login
• 💬 Improved Error Messages — actionable suggestions on every failure
• ⚡ Better Performance — faster emblem resolution and reduced startup time
• 📋 Update & Outdated Commands — ely update and ely outdated are now fully implemented

Quick Start

Installation

# One-line install (Linux/macOS) - Recommended
curl -sSL https://raw.githubusercontent.com/Lo10Th/Elysium/main/scripts/install.sh | bash

# Or with wget
wget -qO- https://raw.githubusercontent.com/Lo10Th/Elysium/main/scripts/install.sh | bash

# Install a specific version
curl -sSL https://raw.githubusercontent.com/Lo10Th/Elysium/main/scripts/install.sh | bash -s -- --version v1.0.0

# Using Go install
go install github.com/Lo10Th/Elysium/cli/cmd/ely@latest

# Download binary from GitHub Releases
# Visit: https://github.com/Lo10Th/Elysium/releases

Pull and Use an Emblem

# Authenticate
ely login

# Pull emblem
ely pull clothing-shop

# View available actions
ely info clothing-shop

# Execute actions
export CLOTHING_SHOP_API_KEY=your-api-key

# List products
ely clothing-shop list-products

# Create product
ely clothing-shop create-product \
  --name "Vintage T-Shirt" \
  --price 29.99 \
  --category shirts \
  --size M \
  --color blue

# Place order
ely clothing-shop create-order \
  --customer-name "John Doe" \
  --customer-email "john@example.com" \
  --customer-address "123 Main St" \
  --items '[{"product_id": 1, "quantity": 2}]'

Stripe Payments Example

Use Stripe's test mode keys (prefixed with sk_test_) to try the Stripe emblem safely without real charges.

# Pull the Stripe emblem
ely pull stripe

# Set your Stripe test API key
export STRIPE_API_KEY=sk_test_...

# List customers
ely stripe list-customers

# List customers filtered by email
ely stripe list-customers --email "customer@example.com"

# Create a customer
ely stripe create-customer \
  --email "customer@example.com" \
  --name "Jane Doe"

# Retrieve a specific customer
ely stripe get-customer --id cus_xyz

# Create a PaymentIntent for $10.00 USD
ely stripe create-payment-intent \
  --amount 1000 \
  --currency usd \
  --customer cus_xyz

# List PaymentIntents for a customer
ely stripe list-payment-intents --customer cus_xyz

# Confirm a PaymentIntent with a test payment method
ely stripe confirm-payment-intent \
  --id pi_xyz \
  --payment_method pm_card_visa

# List charges
ely stripe list-charges --customer cus_xyz

# Retrieve a specific charge
ely stripe get-charge --id ch_xyz

Test mode tip: Stripe test keys start with sk_test_. Use test card numbers (e.g. 4242424242424242) and Stripe's test payment methods (e.g. pm_card_visa) to exercise the full payment flow without real charges. See Stripe testing docs for details.

Authentication Flow

# Browser-based login (opens browser automatically)
ely login
# → Displays a device code and verification URL
# → Opens your browser and waits for authorization
# → Saves credentials on success

# Email/password login (fallback)
ely login --password

# Show current user
ely whoami

# Log out
ely logout

Self-Update

# Update ely to the latest version
ely self-update

# Check for a new version without installing
ely self-update --check

# Install a specific version
ely self-update --version v1.0.0

# Force reinstall even if already up to date
ely self-update --force

Keep Emblems Up to Date

# Check which installed emblems have updates available
ely outdated

# Update a specific emblem
ely update clothing-shop

# Update all installed emblems at once
ely update --all

Architecture

┌─────────────────┐      ┌──────────────────┐      ┌─────────────────┐
│                 │      │                  │      │                 │
│   CLI (ely)     │──────▶   Registry      │◀──────│   Developer     │
│                 │      │   (Supabase)     │      │   (You)         │
│   - Pull        │      │                  │      │                 │
│   - Execute     │      │   - Store        │      │   - Publish     │
│   - Search      │      │   - Search       │      │   - Version     │
│                 │      │   - Auth          │      │                 │
└─────────────────┘      └──────────────────┘      └─────────────────┘
        │                         │                         
        │                         │                         
        ▼                         │                         
┌─────────────────┐               │                         
│   Emblem YAML   │               │                         
│                 │               │                         
│   - Actions     │               │                         
│   - Types       │               │                         
│   - Auth        │               │                         
└─────────────────┘               │                         
        │                         │                         
        ▼                         │                         
┌─────────────────┐               │                         
│   Any API       │◀──────────────┘                         
│                 │                                         
│   - REST        │                                         
│   - GraphQL     │                                         
│   - WebSocket   │                                         
└─────────────────┘                                         

Project Structure

elysium/
├── server/                 # FastAPI registry backend
│   ├── app/
│   │   ├── routes/         # API endpoints
│   │   ├── models.py       # Pydantic models
│   │   ├── database.py     # Supabase client
│   │   └── config.py       # Settings
│   └── requirements.txt
│
├── cli/                    # Go CLI tool
│   ├── cmd/               # Cobra commands
│   ├── internal/
│   │   ├── api/          # Registry client
│   │   ├── config/       # State management
│   │   ├── emblem/       # Parser & validator
│   │   └── executor/     # HTTP requester
│   └── go.mod
│
├── schemas/
│   └── emblem.schema.json # JSON Schema for validation
│
├── examples/
│   └── clothing-shop/
│       └── emblem.yaml    # Complete example
│
└── docs/
    ├── EMBLEM_SPEC.md     # Full specification
    ├── GETTING_STARTED.md # User guide
    └── SERVER_SETUP.md    # Deployment guide

Emblem Specification

apiVersion: v1
name: clothing-shop
version: 1.0.0
description: REST API for online clothing store
baseUrl: https://api.clothing-shop.example.com

auth:
  type: api_key
  keyEnv: CLOTHING_SHOP_API_KEY
  header: X-API-Key

types:
  Product:
    properties:
      id: { type: integer }
      name: { type: string }
      price: { type: number }

actions:
  list-products:
    description: List all products
    method: GET
    path: /products
    parameters:
      - name: category
        type: string
        in: query
        
  create-product:
    description: Create a product
    method: POST
    path: /products
    parameters:
      - name: name
        type: string
        in: body
        required: true

Full specification: docs/EMBLEM_SPEC.md

CLI Reference

Authentication

ely login                 # Browser-based login
ely logout                # Remove credentials
ely whoami               # Show current user

Discovery

ely search <query>       # Search emblems
ely info <name>          # View emblem details
ely list                  # List installed emblems

Installation

ely pull <name>[@version] # Pull emblem
ely init <name>           # Create new emblem scaffold
ely validate ./emblem.yaml # Validate emblem
ely test ./<dir>/         # Test emblem locally

Execution

ely <emblem-name> <action> [flags]

# Examples:
ely clothing-shop list-products
ely clothing-shop get-product --id 1
ely stripe create-customer --email "test@example.com"

API Keys

ely keys list              # List your API keys
ely keys create <name>     # Create new API key
ely keys delete <id>       # Delete API key
ely keys show <id>         # Show key details

Maintenance

ely update <name>          # Update a specific emblem
ely update --all           # Update all installed emblems
ely outdated               # Show emblems with updates available
ely remove <name>          # Uninstall emblem (planned)

CLI Updates

ely self-update            # Update ely to the latest version
ely self-update --check    # Check for updates without installing
ely self-update --version v1.0.0 # Install a specific version
ely self-update --force    # Force reinstall
ely check-updates          # Check if a new ely version is available

Planned Commands (Not Yet Implemented)

The following commands are planned for future releases:

ely remove <name>         # Uninstall emblem
ely publish ./<dir>/      # Publish emblem to registry

Server Endpoints

Authentication

POST /api/auth/register   # Create account
POST /api/auth/login      # Login
POST /api/auth/logout     # Logout
POST /api/auth/refresh    # Refresh token
GET  /api/auth/me         # Current user

Emblems

GET  /api/emblems                    # List all
GET  /api/emblems?category=payments  # Filter
GET  /api/emblems/:name              # Get emblem
GET  /api/emblems/:name/:version     # Get version
POST /api/emblems                    # Publish new (planned)
PUT  /api/emblems/:name              # New version (planned)
DELETE /api/emblems/:name           # Delete (planned)

Search

GET /api/emblems/search?q=query&sort=downloads&limit=20

Setup Guide

Server (Backend)

cd server
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# Edit .env with Supabase credentials
uvicorn app.main:app --reload

Full setup: docs/SERVER_SETUP.md

CLI (Development)

cd cli
go mod tidy
go build -o ely ./cmd
./ely --help

Clothing Shop (Example API)

cd ../clothing_shop
python -m venv env
source env/bin/activate
pip install -r requirements.txt
python app.py
# API runs on http://localhost:5000

Generate API key:

curl -X POST http://localhost:5000/api/auth/generate-key \
  -H "Content-Type: application/json" \
  -d '{"name": "test-key"}'

Development

Run Tests

# Server tests
cd server
pytest tests/ -v

# CLI tests
cd cli
go test ./... -v

# End-to-end
./scripts/e2e-test.sh

Build Distribution

# Build all platforms
./scripts/build-all.sh

# Creates:
# - ely-linux-amd64
# - ely-linux-arm64
# - ely-darwin-amd64
# - ely-darwin-arm64
# - ely-windows-amd64.exe

Create Release

git tag v1.0.0
git push origin v1.0.0
# GitHub Actions builds and uploads binaries

Roadmap

• Emblem specification and schema
• Registry backend (Supabase + FastAPI)
• Go CLI core commands
• Authentication (OAuth + API keys + browser-based device flow)
• Dynamic emblem execution
• Local validation and testing
• Self-update command (ely self-update)
• Update & outdated commands (ely update, ely outdated)
• Improved error messages with actionable suggestions
• Web UI for browsing emblems
• Emblem marketplace
• Private namespaces
• Team collaboration
• API monitoring integration
• Code generation (SDKs)

Breaking Changes

There are no breaking changes in v1.0.0. All existing commands and emblem YAML files are fully compatible with previous versions.

For a complete history of changes see CHANGELOG.md.

Contributing

See CONTRIBUTING.md for guidelines on how to contribute to Elysium.

Quick summary:

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Make changes
4. Run tests (go test ./... and pytest tests/)
5. Commit (git commit -m 'Add amazing feature')
6. Push (git push origin feature/amazing-feature)
7. Open Pull Request

Code Style

Go

• Use gofmt for formatting
• Follow Effective Go
• Add comments for exported functions
• Use meaningful variable names

Python

• Use black for formatting
• Use flake8 for linting
• Use type hints
• Keep functions under 50 lines

License

MIT License - see LICENSE

Documentation

Document	Description
docs/GETTING_STARTED.md	Installation and first steps
docs/EMBLEM_SPEC.md	Full emblem YAML specification
docs/ARCHITECTURE.md	System design and component overview
docs/SERVER_SETUP.md	Deploying the registry server
docs/SECURITY.md	Security policy and vulnerability reporting
docs/TROUBLESHOOTING.md	Common problems and solutions
CONTRIBUTING.md	How to contribute
CHANGELOG.md	Version history

Example Emblems

Emblem	Description
examples/clothing-shop	E-commerce REST API (local development)
examples/stripe	Stripe payments — customers, intents, charges
examples/github	GitHub — repos, issues, pull requests, users
examples/slack	Slack — messages, channels, users

Support

• 📚 Documentation: docs/
• 🐛 Issues: GitHub Issues
• 🔒 Security: docs/SECURITY.md

---

Built with ❤️ for the API economy