@usepapier/cli

The official Papier CLI for template management and code generation.

📦 Installation

npm install -g @usepapier/cli

Or use with npx:

npx @usepapier/cli <command>

🚀 Quick Start

1. Login to Papier

   papier login

2. Initialize a new project

   papier init

3. Sync templates and generate client code

   papier sync

📖 Commands

papier login

Authenticate with your Papier account. Opens a browser window for authentication.

papier login

This stores your authentication token locally for future CLI operations.

papier init

Initialize a new Papier project in your current directory. This command will:

• Prompt you to select an organization (or use the default if you only have one)
• Let you choose one or more projects
• Allow you to select templates from each project
• Generate a .papier/papier.json configuration file

papier init

Example output structure:

.papier/
├── papier.json          # Your template configuration
└── papier-schema.json   # JSON schema for autocomplete

Example papier.json:

{
  "$schema": "./papier-schema.json",
  "organization": "my-org",
  "projects": {
    "marketing": {
      "templates": {
        "welcome-email": "^1.0.0",
        "newsletter": "^2.1.0"
      }
    },
    "transactional": {
      "templates": {
        "password-reset": "^1.2.0"
      }
    }
  }
}

papier sync

Synchronize your template configuration and generate type-safe client code. This command:

• Reads .papier/papier.json
• Resolves template versions based on semver ranges
• Fetches template schemas from the Papier API
• Generates .papier/papier.lock.json with resolved versions
• Generates TypeScript client code with full type safety

papier sync

What gets generated:

.papier/
├── papier.json           # Your configuration
├── papier.lock.json      # Locked template versions and schemas
├── papier-schema.json    # JSON schema
└── index.ts              # Generated type-safe client

When to run:

• After modifying papier.json
• When you want to update to newer template versions
• When templates are updated on the Papier platform

papier generate

Generate client code from an existing lockfile without fetching from the API. Useful for:

• CI/CD pipelines
• Offline development
• Regenerating code after lockfile changes

papier generate

Requirements:

• Requires existing .papier/papier.lock.json (created by papier sync)

papier postinstall

Internal command used by @usepapier/client package. Runs automatically after package installation to generate client code.

⚠️ Note: This is for internal use and typically not run manually.

🏗️ Project Structure

After initialization and sync, your project will have:

your-project/
├── .papier/
│   ├── papier.json         # Configuration (committed to git)
│   ├── papier.lock.json    # Locked versions (committed to git)
│   ├── papier-schema.json  # JSON schema for IDE support
│   └── index.ts            # Generated client (gitignored)
├── src/
│   └── your-code.ts        # Your application code
└── package.json

💡 Workflow

Typical Development Flow

1. Initial Setup

   papier login
   papier init

2. Add Templates

   • Edit .papier/papier.json manually or run papier init again
   • Specify templates with semver version ranges

3. Sync & Generate

   papier sync

4. Use in Your Code

   import { createPapierClient } from './.papier';
   
   const papier = createPapierClient({
     project: 'marketing',
     apiKey: process.env.PAPIER_API_KEY
   });
   
   // Type-safe template usage
   await papier.email('welcome-email').send({
     to: '[email protected]',
     data: {
       name: 'John Doe',
       // ... fully typed based on template schema
     }
   });

Team Collaboration

Developer A:

# Add new template
papier init  # Select additional templates
papier sync  # Update lockfile
git add .papier/papier.json .papier/papier.lock.json
git commit -m "Add password-reset template"
git push

Developer B:

git pull
papier generate  # Generate code from updated lockfile

🔧 Configuration

.papier/papier.json

{
  "$schema": "./papier-schema.json",
  "organization": "your-org-slug",
  "projects": {
    "project-slug": {
      "templates": {
        "template-slug": "version-range"
      }
    }
  }
}

Version Ranges:

• "1.2.3" - Exact version
• "^1.2.3" - Compatible with 1.2.3 (>=1.2.3 <2.0.0)
• "~1.2.3" - Approximately 1.2.3 (>=1.2.3 <1.3.0)
• "*" - Latest version
• ">=1.0.0 <2.0.0" - Range

Environment Variables

PAPIER_API_KEY=your-api-key      # API authentication
PAPIER_ENV=production            # Environment (production/staging/development)
SDK_PAPIER_API_URL=https://...   # Custom API URL (optional)

🔐 Authentication

Authentication tokens are stored in:

• Linux/Mac: ~/.papier/auth.json
• Windows: %USERPROFILE%\.papier\auth.json

To logout, simply delete this file or run papier login again.

📝 Best Practices

1. Version Control

   • ✅ Commit: papier.json, papier.lock.json
   • ❌ Ignore: .papier/index.ts, .papier/*.d.ts (generated code)

2. Version Ranges

   • Use ^ for automatic minor/patch updates
   • Pin exact versions for critical templates
   • Review lockfile changes in PRs

3. CI/CD

   # Example GitHub Actions
   - name: Generate Papier client
     run: |
       npm install -g @usepapier/cli
       papier generate

4. Monorepo Setup

   • Run papier init in each package that needs templates
   • Each package can have its own .papier/ directory
   • Share organization across packages

🐛 Troubleshooting

"You need to login first"

papier login

"papier.json not found"

papier init

"Template not found"

• Verify template slug in Papier dashboard
• Ensure you have access to the project
• Check organization is correct

Type errors after sync

# Regenerate client code
papier generate

# Or full sync
papier sync

🔗 Related Packages

• @usepapier/client - Runtime SDK for using templates
• @papier/render-engine - Template rendering engine

📄 License

MIT

🤝 Contributing

Issues and pull requests welcome!

Made with ❤️ by the Papier team