Skip to main content

​
Requirements

Runtime

  • Bun >= 1.3.0 (recommended) - Node.js >= 20.0.0

TypeScript

TypeScript >= 5.0.0 (for type checking)

​
Install the Client

Choose your preferred package manager: 
bun add @readonly/client

​
Set Up Environment Variables

Add your API key to your environment: 
READONLY_API_KEY=ro_your_api_key_here
Security: Never commit your .env file to version control. Add it to .gitignore: bash .gitignore .env .env.local

​
Get Your API Key

  1. Go to readonly.store
  2. Sign in or create an account
  3. Create a new project or open an existing one
  4. Copy the API key from your project dashboard (starts with ro_)

​
Verify Installation

Run the sync command to verify everything is set up correctly: 
bunx readonly sync
If successful, you’ll see: 
✓ Synced 3 files (12.4 KB)
✓ Type generation complete!

​
Directory Structure

After running sync, you’ll have: 
your-project/
├── node_modules/
│   ├── .cache/
│   │   └── readonly/           # Cached JSON files
│   │       ├── documents.json
│   │       └── config.json
│   └── _generated/
│       └── readonly/           # Generated TypeScript files
│           ├── index.js
│           ├── index.d.ts
│           ├── documents.d.ts
│           └── config.d.ts
└── package.json

​
Next Steps

Quickstart

Follow the quickstart guide to sync your first files.

CLI Reference

Learn about all available commands.

Configuration

Customize cache and output directories.

Usage Guide

Learn how to import and use your files.

​
Troubleshooting

Make sure you’re using bunx readonly or npx readonly to run the CLI. The package is installed locally, not globally.
Set the environment variable before running commands: bash READONLY_API_KEY=ro_your_key bunx readonly sync Or add it to your .env file.
Make sure you’ve run bunx readonly sync at least once to generate the TypeScript types.