Skip to Content
OpenSpec
ReferenceConfiguration

CLI settings (config.json)

Every field of config.json: how the openspec CLI behaves on your machine.

Location

The CLI keeps its machine-level settings at ~/.config/openspec/config.json on macOS and Linux, and %APPDATA%\openspec\config.json on Windows. $XDG_CONFIG_HOME wins on every platform when set. The openspec config command reads and edits it.

Fields

KeyTypeRequiredEffect
profilestring: core or customNoPicks the workflow set openspec init installs
deliverystring: both, skills, or commandsNoRetired in 2.0: read, but no longer changes anything
workflowslist of stringsNoThe workflow list a custom profile installs
featureFlagsmap: flag → booleanNoBoolean feature toggles
defaultStorestringNoMachine-level fallback store for root resolution
skillsScopestring: global or projectNoWhere openspec init puts skills in a project that has none
openersmap: tool id → settingsNoThe tools worksets open in, and how each is launched
telemetrymapNoTelemetry opt-out, anonymous id, and notice-seen state

profile

Which workflow set openspec init installs. Defaults to core: propose, explore, apply, update, sync, and archive. Setting custom installs exactly the workflows list instead.

delivery

Retired in OpenSpec 2.0, which installs skills only. The value is still accepted and read, so older configs stay valid, but it no longer changes what init and update install. Defaults to skills. In 1.x it chose between skills, slash commands, or both (Upgrade to 2.0).

workflows

The workflows a custom profile installs; ignored when the profile is core. Valid ids: propose, explore, new, continue, apply, update, ff, sync, archive, bulk-archive, verify, onboard.

featureFlags

Boolean toggles keyed by flag name, set with openspec config set featureFlags.<flag> true. No flag is read by the CLI today.

defaultStore

The machine-level fallback store id for root resolution, consulted only when no --store flag, local openspec/, or project store: pointer resolves. The full ladder is Root resolution.

skillsScope

Set openspec config set skillsScope project to keep skills in new repos on this machine. The default is global. A project that already has skills keeps them. See setup to switch a repo.

openers

The tools a workset can open in, keyed by tool id. Edit openers in the global config.json with openspec config edit in your terminal.

FieldContract
styleworkspace-file or attach-dirs. Required for a new tool; optional for a built-in.
labelNon-empty string shown in the tool picker. Defaults to the id for a new tool.
commandNon-empty executable name or path. Defaults to the id for a new tool. Put arguments in args, not in this string.
argsArray of strings passed before the workspace file or attach flags. Defaults to [] for a new tool.
attach_flagNon-empty string paired with each member path for attach-dirs. Defaults to --add-dir for a new tool. Ignored for workspace-file.

Built-in overrides: code, cursor, claude, and codex retain any fields you omit. Setting args replaces the entire argument list; [] clears it.

Launch styles: workspace-file passes the generated .code-workspace path to the executable. attach-dirs passes one flag/path pair per member, including the primary member.

Availability: attach-dirs openers, including Claude Code and Codex, are disabled by default. You cannot select or save them with --tool, and OpenSpec refuses to open a workset that already names one. Configuration overrides do not enable the attach-dirs launch style.

Validation: unknown fields, invalid types, and a new tool without style fail when a workset command reads the opener table.

This example adds VS Code Insiders and passes --new-window whenever the built-in VS Code opener launches:

{
  "openers": {
    "code-insiders": {
      "style": "workspace-file",
      "label": "VS Code Insiders"
    },
    "code": {
      "args": ["--new-window"]
    }
  }
}

The corresponding code-insiders or code executable must be installed and available on PATH.

telemetry

The CLI stores your anonymous id and whether the first-run notice was shown. Set telemetry.enabled to false to disable telemetry. You can also opt out with OPENSPEC_TELEMETRY=0 or DO_NOT_TRACK=1 in your environment.

Example

A filled-in config.json:

{
  "profile": "core",
  "featureFlags": {},
  "telemetry": {
    "anonymousId": "5f8a2c1e-4b6d-4f9a-9c3d-7e1b2a8d4c6f",
    "noticeSeen": true
  }
}

On this page