Metadata-Version: 2.4
Name: forkstack
Version: 0.1.0
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Rust
Classifier: Topic :: Software Development :: Build Tools
Requires-Dist: mkdocs-material>=9.7.0 ; extra == 'docs'
Provides-Extra: docs
License-File: LICENSE
Summary: forkstack CLI - instant, isolated development environments using zero-copy database and storage forks
Keywords: cli,database,development,devtools,turso
Home-Page: https://forkstack.xyz
Author-email: Russell Romney <russellromney@gmail.com>
License: Apache-2.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://forkstack.xyz
Project-URL: Repository, https://github.com/russellromney/forkstack
Project-URL: Documentation, https://forkstack.xyz

# forkstack

**Instant, isolated development environments using zero-copy database and storage forks.**

forkstack is a CLI tool for creating fully isolated development environments in seconds. Each developer gets their own copy of your entire stack—database and object storage—without duplicating data or slowing down.

## Installation

```bash
# Recommended: install script
curl -LsSf https://forkstack.xyz/install.sh | sh

# Or with pip/uv
pip install forkstack
uv pip install forkstack

# Or with cargo
cargo install forkstack --bin forks
```

## Why forkstack?

Traditional development environments share databases or require expensive duplication:
- ❌ **Shared dev DB**: Developers step on each other's data
- ❌ **DB per developer**: Expensive, slow to provision, hard to keep in sync
- ❌ **Local-only**: Can't test with production-like data

forkstack gives you the best of all worlds:
- ✅ **Instant creation**: New environments in seconds, not minutes
- ✅ **Zero cost**: Fork-on-write means no data duplication charges
- ✅ **Full isolation**: Each environment has its own DB and storage
- ✅ **Production parity**: Fork from production to test with real data
- ✅ **Easy cleanup**: Delete environments instantly when done

## Quick Start

### 1. Create a config file

Create `.forkstack.toml` in your project:

```toml
[database]
provider = "turso"
organization = "your-org"
production = "my-app-prod"

[storage.uploads]
provider = "tigris"
bucket = "my-app-uploads"
endpoint = "https://fly.storage.tigris.dev"
```

### 2. Set credentials

```bash
export TURSO_API_TOKEN="your-token"
export AWS_ACCESS_KEY_ID="your-key"
export AWS_SECRET_ACCESS_KEY="your-secret"
```

### 3. Create a fork

```bash
$ forks create -n alice
Created fork: alice
Database: libsql://alice-your-org.turso.io
Storage:  uploads: s3://my-app-uploads/forks/alice/
```

### 4. Use your fork

Point your app at the fork URLs, work in isolation, then clean up:

```bash
$ forks delete alice
Deleted fork: alice
```

## CLI Reference

```bash
forks create           # Create fork with random name
forks create -n alice  # Create fork with specific name
forks list             # List all forks
forks delete alice     # Delete a fork
```

## How It Works

```
forks create
    │
    ├── Turso API: Create database branch
    │   └── Zero-copy fork from production DB
    │
    └── S3 API: Copy objects to fork prefix
        └── Full copy (or use Tigris bucket forks)
```

**Database branching** uses Turso's native branching—instant, zero-copy regardless of database size.

**Storage forking** copies objects to a fork-specific prefix. For zero-copy storage, use Tigris bucket forks.

## Supported Services

**Databases** (pick one):
- [Turso](https://turso.tech) - SQLite branches (recommended)
- More coming soon (Neon, PlanetScale)

**Object Storage** (pick one):
- [Tigris](https://www.tigrisdata.com) - S3-compatible with bucket forks (recommended)
- Any S3-compatible storage

## Pattern Benefits

### For Individual Developers
- Test risky changes in isolation
- Work on multiple features simultaneously
- Fork from prod to debug with real data
- Clean up experiments instantly

### For Teams
- No database conflicts between developers
- Easy code review with deployable branches
- Staging environments on-demand
- Safe production debugging

### For CI/CD
- Ephemeral preview environments per PR
- Cost-effective testing at scale
- Automatic cleanup after merge

## Documentation

Full documentation at [forkstack.xyz](https://forkstack.xyz)

- [Getting Started Guide](https://forkstack.xyz/getting-started)
- [Architecture Deep Dive](https://forkstack.xyz/architecture)
- [Database Options](https://forkstack.xyz/databases)
- [Storage Options](https://forkstack.xyz/storage)

## Contributing

Contributions welcome! Submit issues and PRs at [github.com/russellromney/forkstack](https://github.com/russellromney/forkstack)

## License

Apache 2.0 - Use it however you want.

