Skip to content

Improve README.md documentation structure and developer onboarding #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
aditzel merged 3 commits into from
Nov 30, 2025
Merged

Improve README.md documentation structure and developer onboarding #2

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
12ad57e
Initial plan
Copilot Nov 30, 2025
acfced3
Update README.md with improved documentation and better organization
Copilot Nov 30, 2025
1723bd7
Fix Table of Contents link text to match section headers
Copilot Nov 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
182 changes: 138 additions & 44 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,38 +1,81 @@
# wavespeed-cli

[![Test and Build](https://github.com/aditzel/wavespeed-cli/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/aditzel/wavespeed-cli/actions/workflows/test.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
[![Bun](https://img.shields.io/badge/Bun-Runtime-f9f1e1.svg)](https://bun.sh)

A TypeScript CLI for the Wavespeed AI Bytedance Seedream V4 API, built with Bun.
A powerful command-line interface for [Wavespeed AI](https://wavespeed.ai)'s image generation and editing APIs. Generate stunning images from text prompts, edit existing images, and create consistent image sequences—all from your terminal.

## Table of Contents

- [Quick Start](#quick-start)
- [Features](#features)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
- [Multi-model Selection](#multi-model-selection)
Copy link

Copilot AI Nov 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Table of Contents link text "Multi-model Selection" doesn't match the actual section heading "Multi-model selection" (capital vs lowercase 'S'). While the anchor link #multi-model-selection is correct, the inconsistent capitalization in the link text may confuse readers. Consider updating the TOC link text to match: [Multi-model selection](#multi-model-selection)

Suggested change
- [Multi-model Selection](#multi-model-selection)
- [Multi-model selection](#multi-model-selection)

Copilot uses AI. Check for mistakes.
- [Error Handling and Exit Codes](#error-handling-and-exit-codes)
- [Development](#development)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
Copy link

Copilot AI Nov 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Table of Contents is missing several sections that exist in the document: "API Documentation" (line 497), "Pricing" (line 506), and "Support" (line 527). These sections should be added to the TOC for better navigation and discoverability.

Suggested change
- [Contributing](#contributing)
- [Contributing](#contributing)
- [API Documentation](#api-documentation)
- [Pricing](#pricing)
- [Support](#support)

Copilot uses AI. Check for mistakes.
- [License](#license)

## Quick Start

Get up and running in under 2 minutes:

```bash
# Install Bun (if not already installed)
curl -fsSL https://bun.sh/install | bash

# Clone and build
git clone https://github.com/aditzel/wavespeed-cli.git
cd wavespeed-cli
bun install && bun run build && bun link

# Set your API key
export WAVESPEED_API_KEY="your_api_key_here"

# Generate your first image
wavespeed generate --prompt "a photorealistic cat sitting on a windowsill"
```

## Features

- **Text-to-Image Generation**: Create images from text prompts
- **Image Editing**: Modify existing images with prompts
- **Sequential Generation**: Generate consistent image sequences
- **Sequential Editing**: Edit images while maintaining consistency
- **Auto-Download**: Images are automatically downloaded when generation completes
- **Base64 Support**: Decode and save base64-encoded image outputs
- **Config-driven multi-model support**: Select between multiple providers/models via config
### Core Capabilities

## API Documentation
| Feature | Description |
|---------|-------------|
| **Text-to-Image Generation** | Create images from text prompts using state-of-the-art AI models |
| **Image Editing** | Modify existing images with natural language prompts |
| **Sequential Generation** | Generate consistent image sequences for animations or storyboards |
| **Sequential Editing** | Edit multiple images while maintaining visual consistency |

- [Bytedance Seedream V4 (Generate)](https://wavespeed.ai/docs/docs-api/bytedance/bytedance-seedream-v4)
- [Bytedance Seedream V4 Edit](https://wavespeed.ai/docs/docs-api/bytedance/bytedance-seedream-v4-edit)
- [Bytedance Seedream V4 Sequential](https://wavespeed.ai/docs/docs-api/bytedance/bytedance-seedream-v4-sequential)
- [Bytedance Seedream V4 Edit Sequential](https://wavespeed.ai/docs/docs-api/bytedance/bytedance-seedream-v4-edit-sequential)
### Developer Experience

- **Auto-Download**: Images are automatically downloaded when generation completes
- **Base64 Support**: Seamlessly decode and save base64-encoded image outputs
- **Multi-Model Support**: Switch between different AI providers and models via configuration
- **Flexible Configuration**: JSON/YAML config files with environment variable interpolation
- **Comprehensive Validation**: Clear error messages with actionable guidance

## Installation

### Prerequisites

- [Bun](https://bun.sh) installed (`brew install oven-sh/bun/bun` on macOS)
- A Wavespeed API key
Before installing wavespeed-cli, ensure you have:

- **[Bun](https://bun.sh)** (v1.0 or later) - A fast JavaScript runtime
- macOS: `brew install oven-sh/bun/bun`
- Linux/WSL: `curl -fsSL https://bun.sh/install | bash`
- **Wavespeed API Key** - Get one at [wavespeed.ai](https://wavespeed.ai)

### Build and Install

```bash
# Clone the repository
git clone https://github.com/YOUR_USERNAME/wavespeed-cli.git
git clone https://github.com/aditzel/wavespeed-cli.git
cd wavespeed-cli

# Install dependencies
Expand All @@ -45,42 +88,31 @@ bun run build
bun link
```

## Configuration

### Environment Variable (default behavior)
### Set Up Your API Key

By default, the CLI uses the built-in Wavespeed Seedream V4 configuration. You only need:
The CLI requires a Wavespeed API key. Set it as an environment variable:

- `WAVESPEED_API_KEY` set in your environment.

For Fish shell users:
**Bash/Zsh:**
```bash
export WAVESPEED_API_KEY="your_api_key_here"
# Add to ~/.bashrc or ~/.zshrc for persistence
```

**Fish:**
```fish
# Check if the variable exists
echo $WAVESPEED_API_KEY

# If not set, add it globally
set -Ux WAVESPEED_API_KEY "your_api_key_here"

# Reload your configuration
source ~/.config/fish/config.fish
```

For Bash/Zsh users:
## Configuration

```bash
# Add to ~/.bashrc or ~/.zshrc
export WAVESPEED_API_KEY="your_api_key_here"
### Default Configuration

# Reload
source ~/.bashrc # or source ~/.zshrc
```
By default, the CLI uses the built-in Wavespeed Seedream V4 configuration with `WAVESPEED_API_KEY` from your environment. No config file is required for basic usage.

If no config file is present, all commands:
- Use `https://api.wavespeed.ai`
- Use `WAVESPEED_API_KEY`
- Target the Bytedance Seedream V4 endpoints
This preserves backward compatibility.

### Config file discovery (multi-model support)

Expand Down Expand Up @@ -396,6 +428,12 @@ bun run dev

# Build for production
bun run build

# Lint the code
bun run lint

# Format the code
bun run format
```

### Testing
Expand All @@ -404,9 +442,11 @@ bun run build
# Run all tests
bun test

# (Optional helpers if added)
# bun test:watch
# bun test:coverage
# Run tests in watch mode
bun test:watch

# Run tests with coverage
bun test:coverage
```

Test coverage includes:
Expand All @@ -419,18 +459,72 @@ Test coverage includes:
- Config loading and model resolution
- Multi-model selection and listing flags

## Troubleshooting

### Common Issues

**"WAVESPEED_API_KEY is not set"**
```bash
# Verify your API key is set
echo $WAVESPEED_API_KEY

# Set it if missing
export WAVESPEED_API_KEY="your_api_key_here"
```

**"Command not found: wavespeed"**
```bash
# Rebuild and relink the CLI
bun run build && bun link

# Or run directly with Bun
bun run src/index.ts generate --prompt "test"
```

**"Unknown model 'X'"**
- Check your config file with `wavespeed --list-models`
- Ensure the model ID matches exactly (case-sensitive)

**"Invalid size format"**
- Use format: `WIDTHxHEIGHT` or `WIDTH*HEIGHT`
- Minimum: 1024x1024, Maximum: 4096x4096

**Network/API errors**
- Verify your internet connection
- Check if your API key is valid at [wavespeed.ai](https://wavespeed.ai)
- Ensure the API service is available

## API Documentation

For detailed API specifications, see:

- [Bytedance Seedream V4 (Generate)](https://wavespeed.ai/docs/docs-api/bytedance/bytedance-seedream-v4)
- [Bytedance Seedream V4 Edit](https://wavespeed.ai/docs/docs-api/bytedance/bytedance-seedream-v4-edit)
- [Bytedance Seedream V4 Sequential](https://wavespeed.ai/docs/docs-api/bytedance/bytedance-seedream-v4-sequential)
- [Bytedance Seedream V4 Edit Sequential](https://wavespeed.ai/docs/docs-api/bytedance/bytedance-seedream-v4-edit-sequential)

## Pricing

From the API documentation:

- Standard generation: $0.027 per image
- Sequential generation: $0.027 × `max_images`

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

MIT License - see `LICENSE` for details.
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Support

- For API issues: see Wavespeed API documentation.
- For CLI issues: open an issue on GitHub.
- **API Issues**: See [Wavespeed API documentation](https://wavespeed.ai/docs)
- **CLI Issues**: [Open an issue on GitHub](https://github.com/aditzel/wavespeed-cli/issues)