Configuration

Overview

Config is resolved by packages/nikcli/src/config/config.ts with path discovery from config/paths.ts. Files are JSONC, support trailing commas, and are validated against Config.Info. Arrays for plugin and instructions are concatenated and deduplicated instead of simply replaced.

Resolution order

The current source order is precise and matters:

1. Remote well-known config from saved auth records with type wellknown. This is the lowest-precedence layer.
2. Global config from Global.Path.config/nikcli.json.
3. Custom config file from NIKCLI_CONFIG.
4. Project config files discovered upward, unless NIKCLI_DISABLE_PROJECT_CONFIG is set.
5. Inline JSON from NIKCLI_CONFIG_CONTENT.
6. Config directories from ConfigPaths.directories, including global config dir, repo .nikcli dirs, home .nikcli, and NIKCLI_CONFIG_DIR.
7. Command, agent, mode, and plugin entries loaded from those directories.
8. Deprecated mode entries are migrated into agent.
9. NIKCLI_PERMISSION merges into permission.
10. Legacy top-level tools is converted into permission rules.
11. Runtime flag overrides such as NIKCLI_DISABLE_AUTOCOMPACT and NIKCLI_DISABLE_PRUNE are applied.

Where files live

NIKCLI_CONFIG=/path/to/nikcli.json nikcli
NIKCLI_CONFIG_DIR=/path/to/.nikcli nikcli
NIKCLI_DISABLE_PROJECT_CONFIG=1 nikcli

Config tokens

Config text supports {env:VAR} and {file:path} substitutions before JSONC parsing. Relative file paths resolve against the config file's directory. Lines commented with // skip file-token expansion.

{
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{env:OPENAI_API_KEY}"
      }
    },
    "openrouter": {
      "options": {
        "apiKey": "{file:./secrets/openrouter.txt}"
      }
    }
  }
}

Minimal config

{
  "$schema": "https://nikcli-ai.dev/config.json",
  "theme": "tokyonight",
  "model": "openai/gpt-5",
  "small_model": "openai/gpt-5-mini",
  "default_agent": "build",
  "share": "manual",
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{env:OPENAI_API_KEY}"
      }
    }
  },
  "permission": {
    "bash": "ask",
    "edit": "ask",
    "webfetch": "ask"
  }
}

Top-level fields

Anonymous usage reporting

nikcli keeps per-day analytics locally, for the /analytics view. It also contributes those per-day totals, anonymously, to the public stats at nikcli-ai.dev/data — which is how that page can show the models people actually run on their own provider keys rather than only what the nikcli gateway served. This is on by default, because a sample of only the people who opted in would measure those people rather than the community.

Turning it off, in order of precedence:

# either environment variable, no config file needed
DO_NOT_TRACK=1
NIKCLI_DISABLE_ANALYTICS=1

{
  "analytics": {
    "share": false
  }
}

The environment variables win over the config, so a machine or a CI image can opt out without a config file existing at all.

What is sent: date, provider, model, distinct session count, assistant message count, token counts and cost. Along with them goes a random UUID generated on your machine, so a resend replaces a day rather than doubling it — it is never published, and the public feed only ever emits a count of distinct installs.

What is never sent: prompts, responses, file paths, repository names, session titles, account details, or anything about your environment. Set analytics.endpoint to send reports to your own collector instead of nikcli's. A failed report is retried later and never surfaces an error. Run nikcli analytics show to see exactly what would be sent.

Providers

Provider entries are partial models.dev providers plus nikcli-specific options. Use enabled_providers to allow only specific provider ids, or disabled_providers to remove automatic providers.

{
  "enabled_providers": ["openai", "anthropic", "openrouter"],
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    },
    "amazon-bedrock": {
      "options": {
        "region": "us-east-1",
        "profile": "default"
      }
    }
  }
}

Agents and commands

agent config controls primary, subagent, and specialized agents. Deprecated mode entries are migrated into agent with mode: primary. Command templates are loaded from config and from config directories.

MCP and connectors

{
  "mcp": {
    "filesystem": {
      "type": "local",
      "command": ["bunx", "@modelcontextprotocol/server-filesystem", "."]
    },
    "remote-docs": {
      "type": "remote",
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer token" }
    }
  },
  "connectors": {
    "github": { "type": "github", "enabled": true },
    "slack": { "type": "slack", "enabled": true },
    "figma": { "type": "figma", "enabled": true }
  }
}

LSP and formatter

lsp can be false, can disable a built-in server by id, or can define a custom server. Custom LSP servers must provide extensions unless they reuse a known built-in id. Formatter config follows the same pattern: disable all with false, override or disable named formatter entries otherwise.

{
  "lsp": {
    "pyright": { "disabled": true },
    "custom-ts": {
      "command": ["typescript-language-server", "--stdio"],
      "extensions": [".ts", ".tsx"],
      "env": { "NODE_ENV": "development" }
    }
  },
  "formatter": {
    "prettier": {
      "command": ["bunx", "prettier", "--write"],
      "extensions": [".ts", ".tsx", ".json"]
    }
  }
}

Permissions

Permission config accepts either a single action for all permissions, a tool-to-action map, or a tool-to-pattern map. Actions are ask, allow, and deny. The legacy top-level tools boolean map is converted into permission actions.

{
  "permission": {
    "bash": {
      "git status*": "allow",
      "rm *": "deny",
      "*": "ask"
    },
    "edit": "ask",
    "webfetch": "ask",
    "lsp": "ask"
  }
}

TUI and keybinds

Notifications and mobile

Notification config is read by built-in notification plugins. Mobile config currently focuses on Tophat mobile project integration and defaults for platform/destination detection.

{
  "notifications": {
    "todo": {
      "enabled": true,
      "slack": { "enabled": true, "connector": "slack", "channel": "#builds" }
    },
    "notify": {
      "enabled": true,
      "events": { "sessionIdle": true, "permissionAsked": true },
      "rateLimit": { "windowMs": 60000, "maxPerWindow": 20 }
    }
  },
  "mobile": {
    "tophat": {
      "enabled": true,
      "defaultPlatform": "ios",
      "defaultDestination": "simulator"
    }
  }
}

Environment flags

Failure modes

Source anchors