Getting Started

Configuration

FORG is configured through a JSON file, environment variables, and CLI flags. Settings are resolved in this priority order: CLI flags > environment variables > project config > global config > defaults.

Config file location

Platform	Path
macOS / Linux	`~/.forg/config.json`
Windows	`%APPDATA%\forg\config.json`

Read or write values with the CLI:

forg config get api_url
forg config set log_level debug
forg config list          # show all current values

Global config options

// ~/.forg/config.json
{
  "api_url":         "https://forg.pro",
  "port":            6247,
  "log_level":       "info",
  "keystore":        "os",          // "os" | "file://<path>"
  "data_dir":        null,          // null = platform default
  "heartbeat_interval": 30,         // seconds
  "session_timeout": 1800,          // seconds of inactivity = new session
  "emit_timeout":    3000,          // ms to wait for /emit to return
  "tls_verify":      true,
  "proxy":           null           // "http://proxy:3128" or null
}

All config keys

Key	Type	Default	Description
`api_url`	string	`https://forg.pro`	Base URL of the FORG backend. Override for self-hosted.
`port`	number	`6247`	Local agent listener port.
`log_level`	string	`info`	`debug` \| `info` \| `warn` \| `error`
`keystore`	string	`os`	Keystore backend. `os` = native keychain, `file://` = file-backed.
`data_dir`	string \| null	null	Override data directory for caches and logs.
`heartbeat_interval`	number	`30`	Seconds between heartbeat pings to the backend.
`session_timeout`	number	`1800`	Seconds of inactivity before a new session ID is generated.
`emit_timeout`	number	`3000`	Max ms to wait before dropping an /emit call.
`tls_verify`	boolean	`true`	Verify TLS certificates. Set false only in test environments.
`proxy`	string \| null	null	HTTP proxy URL for outbound requests.

Environment variable overrides

Every config key can be overridden with an environment variable prefixed FORG_, uppercased, with dots replaced by underscores:

Config key	Environment variable
`api_url`	`FORG_API_URL`
`port`	`FORG_PORT`
`log_level`	`FORG_LOG_LEVEL`
`keystore`	`FORG_KEYSTORE`
`session_timeout`	`FORG_SESSION_TIMEOUT`
`tls_verify`	`FORG_TLS_VERIFY`
`proxy`	`FORG_PROXY`

Per-project config

Place a .forg.json file in the root of a project directory. Settings here override the global config only when forg is invoked from within that directory tree.

// /path/to/my-project/.forg.json
{
  "project_id": "proj_abc123def456",
  "log_level":  "debug",
  "session_timeout": 300
}

The project_id field tags all signals emitted while in this directory with the given project, enabling per-project cost reporting in the dashboard.

CLI flags

Most config values can be passed as flags for one-off overrides:

forg status --port 6248
forg emit '{}' --log-level debug
forg activate lic_xxx --api-url https://my-forg-instance.com