Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Go 1.25+ - The API server and CLI are written in Go
  • PostgreSQL - For local database development
  • Docker & Docker Compose - For running local infrastructure
  • Cloudflare R2 credentials - For tarball storage (or S3-compatible alternative)
  • OAuth credentials - GitHub and/or Google OAuth app credentials

​
Quick Start

1

Clone and navigate to the repository

git clone https://github.com/your-org/prompts.git
cd prompts
2

Copy environment configuration

cp .env.example .env
3

Configure environment variables

Open .env and fill in the required values:
DATABASE_URL=postgres://prompt:prompt@localhost:5432/promptsdev?sslmode=disable
You can configure one or both OAuth providers. At least one is required for authentication.
4

Install Go dependencies

go mod tidy
5

Start local PostgreSQL

make up
This starts PostgreSQL using Docker Compose with these default credentials:
  • User: prompt
  • Password: prompt
  • Database: promptsdev
  • Port: 5432
The database container includes a health check that waits for PostgreSQL to be ready.
6

Run the API server

make api
The API will:
  • Start on http://localhost:8080
  • Automatically run database migrations on startup
  • Serve all routes under /v1
You should see log output like:
api: config loaded (env=development, port=8080)
api: database connection established
api: migrations completed

​
Makefile Commands

The project includes a comprehensive Makefile for common development tasks:

​
Infrastructure

make up
# Starts local PostgreSQL in Docker

​
Development

make api
# Runs the API server with auto-migrations

​
Testing & Quality

make test
# Runs all Go tests

​
Using the CLI Locally

Run the CLI directly with Go: 
go run ./cmd/cli --help
Common CLI operations: 
go run ./cmd/cli login --provider github
The CLI stores authentication tokens in ~/.prompts/config.json after successful login.

​
Database Migrations

Migrations are located in the migrations/ directory and are automatically applied when the API server starts. Manual migration run: 
go run ./cmd/api
# Migrations run automatically on startup
Migrations are executed on every API startup. Ensure your migration files are idempotent.

​
Docker Compose Configuration

The docker-compose.yml defines the local PostgreSQL service: 
services:
  postgres:
    image: postgres:16-alpine
    container_name: prompts-postgres
    environment:
      POSTGRES_USER: prompt
      POSTGRES_PASSWORD: prompt
      POSTGRES_DB: promptsdev
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
Data is persisted in the postgres_data Docker volume. Use make reset to clear it.

​
Environment Variables Reference

All available environment variables from .env.example:
VariableRequiredDefaultDescription
PORTNo8080API server port
APP_ENVNodevelopmentApplication environment
DATABASE_URLYes-PostgreSQL connection string
JWT_SECRETYes-Secret for signing JWT tokens
JWT_EXPIRY_HOURSNo720JWT token expiry (30 days)
GITHUB_CLIENT_IDConditional-GitHub OAuth app client ID
GITHUB_CLIENT_SECRETConditional-GitHub OAuth app secret
GITHUB_REDIRECT_URLConditional-GitHub OAuth callback URL
GOOGLE_CLIENT_IDConditional-Google OAuth app client ID
GOOGLE_CLIENT_SECRETConditional-Google OAuth app secret
GOOGLE_REDIRECT_URLConditional-Google OAuth callback URL
R2_ACCOUNT_IDYes-Cloudflare R2 account ID
R2_BUCKETYesprompts-tarballsR2 bucket name
R2_ACCESS_KEY_IDYes-R2 access key
R2_SECRET_ACCESS_KEYYes-R2 secret access key
CLI_OAUTH_PORTNo9876Local port for CLI OAuth callback
At least one OAuth provider (GitHub or Google) must be configured for authentication to work.

​
Troubleshooting

​
Migration Errors

Problem: Database migration fails on startup Solution:
  • Verify DATABASE_URL is correct
  • Check PostgreSQL is running: docker ps
  • Ensure database user has proper permissions
  • Check migration files in migrations/ directory

​
OAuth Provider Errors

Problem: “OAuth provider unsupported” error Solution:
  • Ensure provider credentials are configured in .env
  • Verify redirect URLs match your OAuth app configuration
  • Check that at least one provider (GitHub or Google) is fully configured

​
R2 Client Initialization Fails

Problem: R2 storage client fails to initialize Solution:
  • Verify all R2 credentials: R2_ACCOUNT_ID, R2_BUCKET, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY
  • Ensure the bucket exists in your R2 account
  • Check that API keys have proper permissions

​
401 Unauthorized Responses

Problem: CLI requests return 401 errors Solution:
  • Confirm you’ve logged in: go run ./cmd/cli login --provider github
  • Check JWT token exists in ~/.prompts/config.json
  • Verify JWT_SECRET is consistent between logins
  • Token may have expired (default: 30 days)

​
Port Already in Use

Problem: “address already in use” error Solution: 
# Check what's using port 8080
lsof -i :8080

# Change port in .env
PORT=8081

Build docs developers (and LLMs) love

Get started for freeTalk to us