Skip to main content

​
Overview

The ReadOnly CLI provides commands to sync files, generate types, and watch for changes in real-time. 
bunx readonly [command]

​
Commands

​
sync

Fetch files from ReadOnly and generate TypeScript types (one-time operation). 
bunx readonly sync
# or (sync is the default command)
bunx readonly
What it does:
  1. Fetches all files from your project using the API key
  2. Saves files to node_modules/.cache/readonly/
  3. Generates TypeScript type definitions in node_modules/_generated/readonly/
Use case: One-time sync during build processes or initial setup.

​
codegen

Regenerate TypeScript types from cached files without fetching from the server. 
bunx readonly codegen
What it does:
  1. Reads cached files from node_modules/.cache/readonly/
  2. Regenerates TypeScript type definitions
Use case: Useful when you want to regenerate types without re-downloading files.

​
dev / watch

Watch for file changes and sync automatically (real-time). 
bunx readonly dev
# or
bunx readonly watch
What it does:
  1. Establishes a WebSocket connection to ReadOnly
  2. Performs initial sync
  3. Watches for file changes in real-time
  4. Automatically syncs and regenerates types when files are updated
Use case: Development mode - keep this running alongside your dev server.
Press Ctrl+C to stop watching.

​
help

Display help information. 
bunx readonly help
# or
bunx readonly -h
bunx readonly --help

​
Environment Variables

All commands require the following environment variables:

​
READONLY_API_KEY (required)

Your project API key (starts with ro_) 
export READONLY_API_KEY=ro_abc123...

​
READONLY_API_URL (optional)

API URL (defaults to https://api.readonly.store) - only needed for self-hosted instances. 
export READONLY_API_URL=https://api.readonly.store

​
READONLY_CACHE_DIR (optional)

Cache directory name (relative to node_modules/). Defaults to .cache. 
export READONLY_CACHE_DIR=.cache

​
READONLY_OUTPUT_DIR (optional)

Output directory name for generated types (relative to node_modules/). Defaults to _generated. 
export READONLY_OUTPUT_DIR=_generated

​
Usage Examples

​
Basic Sync

READONLY_API_KEY=ro_abc123... bunx readonly sync

​
Development Mode

Keep this running alongside your dev server: 
READONLY_API_KEY=ro_abc123... bunx readonly dev

​
Using .env File

Create a .env file:
.env
READONLY_API_KEY=ro_abc123...
Then run commands without prefixing: 
bunx readonly sync
bunx readonly dev

​
Production

Run alongside your application: 
{
  "scripts": {
    "start": "concurrently \"node server.js\" \"readonly dev\""
  }
}

​
Error Handling

The CLI includes automatic retry logic with exponential backoff for network errors:
  • Initial retry delay: 1 second
  • Maximum retry delay: 30 seconds
  • Backoff strategy: Exponential
If the API key is invalid or the project doesn’t exist, the CLI will exit immediately without retrying.

​
Exit Codes

CodeDescription
0Success
1Error occurred

​
Next Steps

Configuration

Learn about configuration options.

Usage Guide

Learn how to use synced files.

Installation

Installation and setup guide.

Troubleshooting

Common issues and solutions.