# Configuration Configure the Paradoc CLI Canonical URL: https://docs.paradoc.dev/cli/configuration/ The CLI reads settings from two places: a **global config** for user-wide preferences, and the **project manifest** for project-specific overrides. This page explains the configuration system, including environment variables, cache, and proxy support. ## Global configuration The global config lives at `~/.paradoc/config.json`. It applies to all projects unless overridden. ```json { "$schema": "https://schema.paradoc.dev/config.json", "defaults": { "output": "json", "artifactsDir": "artifacts" }, "registries": { "@company": "https://registry.company.com" }, "cache": { "ttl": 3600, "directory": "~/.paradoc/cache" }, "security": { "allowedContentTypes": ["application/vnd.acme.form+json"] }, "telemetry": { "enabled": false } } ``` ### Fields | Field | Type | Default | Description | | ------------------------------ | ------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `defaults.output` | string | `"json"` | Default output format (`json`, `yaml`, `typed`, `ts`) | | `defaults.artifactsDir` | string | `"artifacts"` | Default directory for downloaded artifacts | | `registries` | object | — | Registry configuration by namespace. An artifact reference always names its namespace, as in `@acme/w9`. `@paradoc` is reserved and built in; an entry for it is an error | | `cache.ttl` | number | `3600` | Cache time-to-live in seconds | | `cache.directory` | string | `"~/.paradoc/cache"` | Cache storage directory. `~` uses your home directory; relative paths use the directory containing the config file. | | `security.allowedContentTypes` | array | — | Content types added to the built-in download defaults. This cannot narrow the defaults | | `telemetry.enabled` | boolean | `true` | Set to `false` to turn off [telemetry](#telemetry) | | `anonymousId` | string | — | Anonymous telemetry ID. The CLI creates it once and keeps it across resets | The CLI validates this file each time it reads or writes it. A missing file means no settings. If the file is not valid JSON, or has a key or value the schema does not accept, the command stops with an error that names the file and each bad key. The CLI does not change the file; fix it by hand. ## Project overrides The `paradoc.json` manifest can override global settings on a per-project basis. These fields take precedence over the global config: * `artifacts.output` — output format * `artifacts.dir` — artifacts directory * `registries` — registry mappings * `cache.ttl` and `cache.directory` — cache settings * `security` — download settings See the [project manifest](/cli/projects#the-project-manifest) reference for full details. ## Precedence When resolving a setting, the CLI checks in this order: 1. **CLI flags** (highest priority) 2. **Project config** (`paradoc.json`) 3. **Global config** (`~/.paradoc/config.json`) 4. **Built-in defaults** (lowest priority) For registries, a project-level namespace mapping always wins over the same namespace in the global config. ## Global flags These flags can be passed to any command: | Flag | Description | | ---------------- | ------------------------------------- | | `--no-telemetry` | Disable telemetry for this invocation | | `-h, --help` | Display help for the command | | `-v, --version` | Display the CLI version | ```bash paradoc --no-telemetry add @paradoc/w9 ``` ## The configure wizard The [`paradoc configure`](/cli/commands/configure) command walks you through each setting interactively and saves results to the global config: ```bash paradoc configure ``` The wizard covers output format, artifacts directory, cache TTL, and telemetry. Press Enter at any prompt to keep the current value. ## Environment variables The CLI reads these environment variables: | Variable | Purpose | | ------------------------------ | ------------------------------------------------------------------------------------------- | | `PARADOC_NO_UPDATE_CHECK=1` | Turn off the [update check](#update-check) | | `PARADOC_TELEMETRY_DISABLED=1` | Turn off [telemetry](#telemetry) | | `PARADOC_TELEMETRY_DEBUG=1` | Log telemetry events to the console | | `DO_NOT_TRACK=1` | Turn off telemetry (cross-tool standard) | | `PARADOC_TELEMETRY_URL` | Send [telemetry](#telemetry) to another origin, such as `https://telemetry-dev.paradoc.dev` | | `CI` | Turn off the update check when set | | `HTTPS_PROXY`, `HTTP_PROXY` | Send requests through a [proxy](#proxy-support) | Registry URLs and headers also support `${VAR_NAME}` expansion: ```json { "registries": { "@private": { "url": "https://${PRIVATE_REGISTRY_HOST}", "headers": { "Authorization": "Bearer ${REGISTRY_TOKEN}" } } } } ``` The URL itself must remain a valid URL before expansion, so put placeholders inside a URL rather than using a placeholder as the entire value. Header values may be free-form placeholders. The CLI errors if a referenced environment variable is not set. Expansion works in both the global config and project manifest. ## Cache Registry data is cached locally at `~/.paradoc/cache/` to speed up repeated operations. The default TTL is 1 hour (3600 seconds). Override the TTL globally in the config: ```json { "cache": { "ttl": 7200 } } ``` Or per registry: ```json { "registries": { "@acme": { "url": "https://registry.acme.com", "cache": { "ttl": 300 } } } } ``` Manage the cache with [`paradoc cache`](/cli/commands/cache): ```bash paradoc cache stats # Show cache statistics paradoc cache clear # Clear all cached data paradoc cache invalidate @acme # Invalidate a specific registry ``` ## Proxy support The CLI respects standard proxy environment variables for outbound HTTP requests: * `HTTPS_PROXY` / `https_proxy` * `HTTP_PROXY` / `http_proxy` ```bash export HTTPS_PROXY=http://proxy.example.com:8080 paradoc search lease ``` ## Update check Once a day, the CLI checks npm for a newer `paradoc-cli` and prints a one-line notice after the command output, with the command to update it. The check is skipped when `CI` is set or output is not a terminal. To turn it off: ```bash export PARADOC_NO_UPDATE_CHECK=1 ``` ## Telemetry The CLI sends anonymous events to one endpoint, `https://telemetry.paradoc.dev/v1/events/anonymous`. The events are `project.initialized`, `artifact.installed`, `registry.added`, and `directory.installed`. Events include the operating system, CPU architecture, Node.js version, and whether the CLI is running in CI. Public-registry installs also include the registry origin, artifact name, artifact version, and artifact kind. For a public-registry install the CLI sends `directory.installed` with those same fields, so directories can count installs. No personal information or artifact content is collected. Telemetry can be disabled in three ways: **CLI flag** (per invocation): ```bash paradoc --no-telemetry add @paradoc/w9 ``` **Global config** (persistent): ```json { "telemetry": { "enabled": false } } ``` **Environment variables:** | Variable | Purpose | | ------------------------------ | ------------------------------------------------------------------------------------------ | | `PARADOC_TELEMETRY_DISABLED=1` | Disable telemetry | | `DO_NOT_TRACK=1` | Disable telemetry (cross-tool standard) | | `PARADOC_TELEMETRY_DEBUG=1` | Log telemetry events to console | | `PARADOC_TELEMETRY_URL` | Send events to another origin, such as `https://telemetry-dev.paradoc.dev` for development | When multiple settings conflict, the CLI checks in this order: CLI flag, environment variables, global config. Any opt-out at any level disables telemetry entirely. A registry can disable its own install telemetry with `enableTelemetry: false`, or only the `directory.installed` event with `enableDirectory: false`. The publisher sets both in `registry.config.json`, and [`registry compile`](/cli/commands/registry/compile) writes them to `registry.json`.