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

# Installation

> Install the ReadOnly client in your project

## Requirements

<CardGroup cols={2}>
  <Card title="Runtime" icon="terminal">
    * Bun >= 1.3.0 (recommended) - Node.js >= 20.0.0
  </Card>

  <Card title="TypeScript" icon="code">
    TypeScript >= 5.0.0 (for type checking)
  </Card>
</CardGroup>

## Install the Client

Choose your preferred package manager:

<CodeGroup>
  ```bash Bun theme={null}
  bun add @readonlystore/client
  ```

  ```bash npm theme={null}
  npm install @readonlystore/client
  ```

  ```bash pnpm theme={null}
  pnpm add @readonlystore/client
  ```

  ```bash yarn theme={null}
  yarn add @readonlystore/client
  ```
</CodeGroup>

## Set Up Environment Variables

Add your API key to your environment:

<CodeGroup>
  ```bash .env theme={null}
  READONLY_API_KEY=ro_your_api_key_here
  ```

  ```bash Shell theme={null}
  export READONLY_API_KEY=ro_your_api_key_here
  ```
</CodeGroup>

<Warning>
  **Security**: Never commit your `.env` file to version control. Add it to `.gitignore`: `bash .gitignore .env
    	.env.local `
</Warning>

## Get Your API Key

1. Go to [readonly.store](https://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:

```bash theme={null}
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

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Follow the quickstart guide to sync your first files.
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/client/cli-reference">
    Learn about all available commands.
  </Card>

  <Card title="Configuration" icon="gear" href="/client/configuration">
    Customize cache and output directories.
  </Card>

  <Card title="Usage Guide" icon="code" href="/client/usage">
    Learn how to import and use your files.
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Command not found: readonly">
    Make sure you're using `bunx readonly` or `npx readonly` to run the CLI. The package is installed locally, not
    globally.
  </Accordion>

  <Accordion title="Missing READONLY_API_KEY">
    Set the environment variable before running commands: `bash READONLY_API_KEY=ro_your_key bunx readonly sync
        		` Or add it to your `.env` file.
  </Accordion>

  <Accordion title="Type errors when importing">
    Make sure you've run `bunx readonly sync` at least once to generate the TypeScript types.
  </Accordion>
</AccordionGroup>