> ## Documentation Index
> Fetch the complete documentation index at: https://docs.audx.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure audx with audx.json

> Configure the audx CLI with audx.json: where sound files go, which theme and registry to use, and how audx runs in CI and scripts.

## audx.json

`init` creates `audx.json` at your project root. `add` and `theme` create it too if it's missing.

```json audx.json theme={null}
{
  "$schema": "https://audx.site/schemas/config.json",
  "theme": "minimal",
  "dir": "src/sounds"
}
```

**theme** `string` (default: minimal)

Where new sounds come from: a built-in theme name, a URL, or a path to a theme `.json` file. `audx theme <name>` updates it.

**dir** `string`

Where sound modules are written, relative to the project root. Defaults to `src/sounds` if a `src` folder exists, then `lib/sounds` if `lib` exists, otherwise `sounds`.

**registry** `string`

Override the theme registry URL. You rarely need this outside local development of audx itself.

## Registry

The CLI loads built-in themes from `https://audx.site/api`. Override it with the `AUDX_REGISTRY` environment variable, which takes priority over `registry` in `audx.json`:

```bash theme={null}
AUDX_REGISTRY=http://localhost:3000/api npx @litlab/audx list --themes
```

If the registry can't be reached, `list --themes` falls back to the built-in theme names and says it's offline.

## How the CLI reads your project

| What | How it's detected |
| - | - |
| TypeScript or JavaScript | Writes `.ts` files if there's a `tsconfig.json` or a `typescript` dependency, otherwise `.js`. |
| Import path | Uses a matching `paths` alias from `tsconfig.json` or `jsconfig.json`, like `@/sounds`. Otherwise prints a relative path. |
| Package manager | Lockfile first (`bun.lock`, `pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`), then the package manager that ran the CLI, then npm. |
| Project root | The current directory. Use `--cwd <path>` to run against another one. |

## Running in CI and scripts

The CLI only prompts when stdin and stdout are both terminals. It never prompts when the `CI` environment variable is set or when you pass `--yes`. Without prompts it uses defaults:

* `init` writes the default directory and theme (or `--dir` and `--theme`) and adds the starter sounds.
* `add` needs sound names or `--all`.
* Sounds that are already installed are skipped unless you pass `--overwrite`.

```bash theme={null}
npx @litlab/audx init --yes --theme retro --no-install
npx @litlab/audx add click success error --yes
```

## Generated files

Each sound module starts with a header the CLI reads back:

```ts theme={null}
// @audx {"theme":"minimal","sound":"click"}
```

* `theme` records where the sound came from, so `update` checks the right theme.
* `custom: true` marks a sound customized on audx.site. `theme` and `update` skip these unless you pass `--force` to `theme`.

`index.ts` in the sounds directory is regenerated by `add` and `remove`. Don't edit it by hand.

Sound names that are reserved words get a suffix: `delete` is exported as `deleteSound`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.