Configuration

Last updated on

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 ~/.asterdoc/config.json. It applies to all projects unless overridden.

{
  "$schema": "https://schema.asterdoc.com/config.json",
  "defaults": {
    "output": "json",
    "artifactsDir": "artifacts"
  },
  "registries": {
    "@company": "https://registry.company.com"
  },
  "cache": {
    "ttl": 3600,
    "directory": "~/.asterdoc/cache"
  },
  "security": {
    "allowedContentTypes": ["application/vnd.acme.form+json"]
  },
  "telemetry": {
    "enabled": false
  }
}

Fields

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 asterdoc.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 reference for full details.

Precedence

When resolving a setting, the CLI checks in this order:

1. CLI flags (highest priority)
2. Project config (asterdoc.json)
3. Global config (~/.asterdoc/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:

asterdoc --no-telemetry add @asterdoc/w9

The configure wizard

The asterdoc configure command walks you through each setting interactively and saves results to the global config:

asterdoc 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:

Registry URLs and headers also support ${VAR_NAME} expansion:

{
  "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 ~/.asterdoc/cache/ to speed up repeated operations. The default TTL is 1 hour (3600 seconds).

Override the TTL globally in the config:

{
  "cache": {
    "ttl": 7200
  }
}

Or per registry:

{
  "registries": {
    "@acme": {
      "url": "https://registry.acme.com",
      "cache": {
        "ttl": 300
      }
    }
  }
}

Manage the cache with asterdoc cache:

asterdoc cache stats         # Show cache statistics
asterdoc cache clear         # Clear all cached data
asterdoc 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

export HTTPS_PROXY=http://proxy.example.com:8080
asterdoc search lease

Update check

Once a day, the CLI checks npm for a newer version of asterdoc 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:

export ASTERDOC_NO_UPDATE_CHECK=1

Telemetry

The CLI sends anonymous events to one endpoint, https://telemetry.asterdoc.com/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):

asterdoc --no-telemetry add @asterdoc/w9

Global config (persistent):

{
  "telemetry": {
    "enabled": false
  }
}

Environment variables:

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 writes them to registry.json.