> ## Documentation Index
> Fetch the complete documentation index at: https://docs.readonly.store/llms.txt
> Use this file to discover all available pages before exploring further.
# CLI Reference
> Complete reference for all ReadOnly CLI commands
## Overview
The ReadOnly CLI provides commands to sync files, generate types, and watch for changes in real-time.
```bash theme={null}
bunx readonly [command]
```
## Commands
### `sync`
Fetch files from ReadOnly and generate TypeScript types (one-time operation).
```bash theme={null}
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.
```bash theme={null}
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).
```bash theme={null}
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.
```bash theme={null}
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_`)
```bash theme={null}
export READONLY_API_KEY=ro_abc123...
```
### `READONLY_API_URL` (optional)
API URL (defaults to `https://api.readonly.store`) - only needed for self-hosted instances.
```bash theme={null}
export READONLY_API_URL=https://api.readonly.store
```
### `READONLY_CACHE_DIR` (optional)
Cache directory name (relative to `node_modules/`). Defaults to `.cache`.
```bash theme={null}
export READONLY_CACHE_DIR=.cache
```
### `READONLY_OUTPUT_DIR` (optional)
Output directory name for generated types (relative to `node_modules/`). Defaults to `_generated`.
```bash theme={null}
export READONLY_OUTPUT_DIR=_generated
```
***
## Usage Examples
### Basic Sync
```bash theme={null}
READONLY_API_KEY=ro_abc123... bunx readonly sync
```
### Development Mode
Keep this running alongside your dev server:
```bash theme={null}
READONLY_API_KEY=ro_abc123... bunx readonly dev
```
### Using .env File
Create a `.env` file:
```bash .env theme={null}
READONLY_API_KEY=ro_abc123...
```
Then run commands without prefixing:
```bash theme={null}
bunx readonly sync
bunx readonly dev
```
### Production
Run alongside your application:
```json package.json theme={null}
{
"scripts": {
"start": "concurrently \"node server.js\" \"readonly dev\""
}
}
```
```bash Shell theme={null}
readonly dev & node server.js
```
```yaml Docker Compose theme={null}
services:
app:
command: sh -c "readonly dev & node server.js"
environment:
- READONLY_API_KEY=${READONLY_API_KEY}
```
***
## 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
| Code | Description |
| ---- | -------------- |
| `0` | Success |
| `1` | Error occurred |
***
## Next Steps
Learn about configuration options.
Learn how to use synced files.
Installation and setup guide.
Common issues and solutions.