• Features
• Installation
  • Pre-compiled Binaries
  • From Source
• Usage
  • Command-Line Interface (CLI)
    • Commands and Options
    • Examples
  • HTTP API Server
    • Starting the Server
    • Server Environments
    • API Endpoints
    • API Documentation
    • API Examples
    • Server Configuration
• Development

pseudoc is a tool for generating placeholder documents to support testing and development workflows. Similar to how Lorem Ipsum provides placeholder text and picsum.photos provides placeholder images, pseudoc generates various types of fake documents to aid in development and testing scenarios.

• Multiple Document Formats: Generate PDF, DOCX, and XLSX files.
• Dual Interface: Use it as a command-line tool or as an HTTP server.
• Customizable Output: Control the number of documents, pages, sheets, and filenames.
• Reproducible Generation: Use a seed to generate the same documents every time.
• Cross-Platform: A single, self-contained binary for all major platforms (Windows, macOS, Linux).
• Lightweight & Fast: Minimal dependencies and optimized for quick document generation.

Pre-compiled binaries for all major platforms are available on the GitHub Releases page. Download the appropriate binary for your system, add it somewhere appropriate, e.g. a directory in your PATH, and you're ready to go.

If you have Go installed, you can build pseudoc from source:

git clone https://github.com/engineervix/pseudoc.git
cd pseudoc
go build -o bin/pseudoc ./cmd/pseudoc

pseudoc can be used as a command-line tool or as an HTTP server.

The CLI is perfect for scripting and local document generation.

USAGE:
  pseudoc [command] [options]

COMMANDS:
  pdf                          Generate PDF document
  docx, word                   Generate Word document
  xlsx, spreadsheet, sheet     Generate Excel spreadsheet
  random                       Generate random document type
  serve, server                Start HTTP API server
  version, -v, --version       Show version information
  help, -h, --help             Show this help message

OPTIONS:
  --count N                    Number of documents to generate (default: 1)
  --output-dir DIR             Directory to store output files (default: current directory)
  --filename NAME              Base filename (default: auto-generated with timestamp)
  --seed VALUE                 Set random seed for reproducible output
  --quiet                      Suppress output for scripting
  --dry-run                    Preview what would be generated without creating files

FORMAT-SPECIFIC OPTIONS:
  --pages N                    For PDF/DOCX: Number of pages (default: 1)
  --sheets N                   For XLSX: Number of sheets (default: 1)

• Generate a single PDF:

  pseudoc pdf

• Generate 5 Word documents with 3 pages each:

  pseudoc docx --count 5 --pages 3

• Generate an Excel file with a custom filename and 4 sheets:

  pseudoc xlsx --filename my-data --sheets 4

• Generate 10 random documents in a specific directory:

  pseudoc random --count 10 --output-dir ./test-files

• Generate reproducible documents with a seed:

  pseudoc random --seed 42 --count 5

Start the server to generate documents via HTTP requests. This is useful for various kinds of integrations.

pseudoc serve

By default, the server starts on localhost:8080 in development mode. You can customize the host, port, and environment:

pseudoc serve --host 0.0.0.0 --port 3000 --env production

• development (default): Optimized for local testing. Security features like HSTS are disabled to allow for easy testing over plain HTTP.
• production: Intended for deployment. Stricter security headers are enabled. The server should be run behind a TLS proxy (like Nginx or a cloud load balancer) in this mode.

• GET /health: Health check endpoint.
• GET /api/v1/info: Returns server information and capabilities.
• GET /api/v1/generate/{type}: Generate a document.
• POST /api/v1/generate: Generate a document with a JSON config.
• GET /metrics: Server metrics endpoint (when enabled).
• GET /docs: Interactive API documentation (Swagger UI).

The server provides interactive API documentation via Swagger UI at /docs. This includes:

• Interactive Testing: Try out API endpoints directly from the browser
• Request/Response Examples: See example requests and responses for all endpoints
• Schema Documentation: Detailed documentation of all request and response formats
• Parameter Validation: Real-time validation of API parameters

Visit http://localhost:8080/docs when the server is running to explore the full API documentation.

• Generate a 3-page PDF using a GET request:

  curl "http://localhost:8080/api/v1/generate/pdf?pages=3" -o document.pdf

• Generate a random document with a specific seed:

  curl "http://localhost:8080/api/v1/generate/random?seed=42" -o random-doc

• Generate a 5-page DOCX using a POST request:

  curl -X POST "http://localhost:8080/api/v1/generate" \
    -H "Content-Type: application/json" \
    -d '{"type":"docx","pages":5,"seed":123}' \
    -o document.docx

When using the GET /api/v1/generate/random endpoint, the server will generate a document of a randomly selected type directly. Both GET and POST requests include the X-Pseudoc-Generated-Type response header to indicate which document type was generated.

# Generate a random document - the type will be determined by the server
curl "http://localhost:8080/api/v1/generate/random?seed=42" -o random-doc

Use the -L -J -O flags to automatically save the file with the server-provided filename and extension:

# The server provides the correct filename via Content-Disposition header
curl -L -J -O "http://localhost:8080/api/v1/generate/random?seed=42"

You can check the generated document type from the response header:

curl -I "http://localhost:8080/api/v1/generate/random?seed=42"
# Look for: X-Pseudoc-Generated-Type: pdf

The server supports various configuration options for production deployment:

• CORS: Disabled by default for security. Enable by setting allowed origins.
• Rate Limiting: 60 requests per minute by default. Set to 0 to disable.
• Metrics: Disabled by default. Enable with --metrics flag. Basic authentication can be configured programmatically.
• Request Timeout: 30 seconds by default.
• Max File Size: 100MB limit for generated documents.

Example with custom configuration:

# Enable metrics endpoint
pseudoc serve --metrics

# Custom rate limiting and CORS
pseudoc serve --rate-limit 120 --cors-allowed-origins "https://example.com,https://app.example.com"

# Production setup with custom timeout and logging
pseudoc serve --env production --timeout 60s --log-level warn

This project uses just as a command runner. See the justfile for available commands.

• Build the project:

  just build

• Run tests:

  just test

• Run the tool locally:

  just run -- pdf --count 2

• Generate API documentation:

  just docs