Skip to main content

​
Overview

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

​
Commands

​
sync

Fetch files from ReadOnly and generate TypeScript types (one-time operation).
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.
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).
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.

​
Environment Variables

All commands require the following environment variables:

​
READONLY_API_KEY (required)

Your project API key (starts with ro_)

​
READONLY_API_URL (optional)

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

​
READONLY_CACHE_DIR (optional)

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

​
READONLY_OUTPUT_DIR (optional)

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

​
Usage Examples

​
Basic Sync

​
Development Mode

Keep this running alongside your dev server:

​
Using .env File

Create a .env file:
.env
Then run commands without prefixing:

​
Production

Run alongside your application:

​
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

​
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.