Documentation

Everything you need to know about using punt.sh

Quick Start

CLI (Recommended)

The CLI provides the best experience with colored output, progress indicators, and easy options.

# Install globally
npm install -g @lance0/punt    # or: bun install -g @lance0/punt

# Share a file (auto-detects language for syntax highlighting)
punt src/index.ts
punt config.yaml

# Or pipe command output (preserves ANSI colors)
npm test 2>&1 | punt
docker logs myapp | punt

No Installation (curl)

Works anywhere with curl - no installation needed.

command | curl -X POST --data-binary @- https://punt.sh/api/paste

Why Sign In?

punt.sh works great without an account, but signing in with GitHub unlocks higher limits and paste management.

# Sign in via CLI
punt login

# Check who you're logged in as
punt whoami

# All pastes created while logged in are linked to your account
docker logs myapp | punt --ttl 30d

Features

ANSI Color Preservation

By default, punt.sh preserves terminal colors. ANSI escape codes are rendered as styled HTML, so your terminal output looks exactly as intended - no more colorless pastes in Slack or Discord.

# Just pipe any command - colors are preserved automatically
npm test 2>&1 | punt
docker logs myapp | punt
kubectl describe pod mypod | punt

Syntax Highlighting

For code snippets (not terminal output), use the --lang flag to enable syntax highlighting with 66 supported languages.

Auto-Detection

Pass a file directly and punt auto-detects the language from the extension:

# Direct file argument (recommended) - auto-detects language
punt src/index.ts                # Detects TypeScript
punt script.py                   # Detects Python
punt config.yaml                 # Detects YAML

# Or pipe content - specify language explicitly for stdin
docker logs myapp | punt --lang json
kubectl get pods -o yaml | punt --lang yaml

Language Aliases

Use short aliases for common languages:

cat app.js | punt --lang js       # javascript
cat index.ts | punt --lang ts     # typescript
cat script.py | punt --lang py    # python
cat main.rs | punt --lang rs      # rust
cat run.sh | punt --lang sh       # bash
cat config.yml | punt --lang yml  # yaml

Burn After Read

Self-destructing pastes that are automatically deleted after being viewed once. Perfect for sensitive logs or one-time shares.

# CLI
cat secret.txt | punt --burn

# curl
cat secret.txt | curl -H "X-Burn-After-Read: 1" -X POST --data-binary @- https://punt.sh/api/paste

Private Pastes

Generates a view key that's required to access the paste. Share the key only with people who need to see it.

# CLI - returns URL with ?key=xxx appended
echo "secret" | punt --private

# curl
echo "secret" | curl -H "X-Private: 1" -X POST --data-binary @- https://punt.sh/api/paste

Custom TTL

Set how long your paste lives. Default is 24 hours.

# TTL format: number + unit (m=minutes, h=hours, d=days)
command | punt --ttl 30m     # 30 minutes
command | punt --ttl 2h      # 2 hours
command | punt --ttl 7d      # 7 days (max for anonymous)
command | punt --ttl 30d     # 30 days (requires sign in)

# curl
command | curl -H "X-TTL: 1h" -X POST --data-binary @- https://punt.sh/api/paste

CLI Reference

API Reference

Create Paste

POST /api/paste
Content-Type: text/plain

# Headers (all optional):
X-TTL: 1h              # Expiry time (30m, 2h, 7d, etc.)
X-Burn-After-Read: 1   # Delete after first view
X-Private: 1           # Require view key
X-Language: typescript # Syntax highlighting language
Authorization: Bearer punt_xxx  # API token (optional)

Response

🏈 Punted!

   URL  https://punt.sh/abc123
   Raw  https://punt.sh/abc123/raw
   Expires in 24h
   Delete key: xyz789abc

Response headers include:

X-Paste-Id: abc123
X-Delete-Key: xyz789abc
X-RateLimit-Remaining: 99
X-Language: typescript  // if syntax highlighting was used

Get Paste

GET /:id          # HTML view with syntax highlighting
GET /:id/raw      # Raw content (original text)
GET /:id?key=xxx  # Private paste with view key

Delete Paste

DELETE /api/paste/:id/:deleteKey

# Response
{
  "success": true,
  "message": "Paste deleted"
}

Example: Create Paste with curl

# Create a paste
$ echo "Hello, World!" | curl -X POST --data-binary @- https://punt.sh/api/paste

🏈 Punted!

   URL  https://punt.sh/abc123
   Raw  https://punt.sh/abc123/raw
   Expires in 24h
   Delete key: xyz789abc

# Delete the paste using the delete key
$ curl -X DELETE https://punt.sh/api/paste/abc123/xyz789abc

Rate Limits

Rate limit headers are included in API responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705315200

FAQ