Skip to content

CONFIGURATION.md

Latest commit

 

History

History
387 lines (311 loc) · 16.3 KB

CONFIGURATION.md

File metadata and controls

387 lines (311 loc) · 16.3 KB
Raw

Configuration

English | 简体中文

The CLI follows the current ZCode runtime's provider registry schema. General runtime settings and provider configuration live in separate files.

Configuration files

File Purpose
~/.zcode/cli/setting.json CLI theme, notifications, tools, storage and other runtime settings
~/.zcode/v2/setting.json Existing Desktop language and memory preferences, read without modification
~/.zcode/v2/provider_config.json Providers, model metadata overrides and the default model
~/.zcode/v2/credentials.json Credentials persisted by the native runtime

On Windows, use %USERPROFILE% in place of ~. The provider file is shared with ZCode Desktop by default: changing providers or the saved default affects both clients. /model changes only the current CLI session.

Set ZCODE_PERSONAL_PROVIDER_CONFIG_FILE to a separate file to isolate provider settings. ZCODE_DATA_BASE_DIR changes the native runtime's base directory, including its provider and credential storage. General CLI settings still use the user's ~/.zcode/cli/setting.json.

On first launch, the CLI creates a credential-free general configuration from setting.example.json. Existing files are not replaced. Provider settings are created by native login or configured using provider.example.json. The complete provider field reference explains every supported personal configuration field, Desktop editor mapping and automatic catalog inheritance.

Startup migration

The CLI follows the Desktop migration rules and uses the runtime's native parser and file-locked provider repository. Desktop imports its legacy providers when its native file is first created. CLI startup performs one additional, one-time merge from ~/.zcode/cli/config.json, because the shared provider file may already have been created by Desktop.

Only missing personal provider IDs are added. Existing provider definitions, model overrides, ordering and the shared default selection are preserved. Account providers and encrypted secrets are excluded. Deleted models are excluded; native model IDs and provider aliases are normalized by the upstream parser. Unsupported provider configurations are recorded as skipped.

CLI-specific fields move to ~/.zcode/cli/setting.json; provider, main/lite and catalog-overlay fields are omitted. The original file remains intact. A marker under ~/.zcode/cli/migrations/ records completion for each target provider file, so later startup does not re-import providers that a user has deleted. A separate settings-v1.json marker prevents a reset of CLI settings from importing the old settings again. The old file is never used as a runtime configuration fallback. Invalid new files are reported rather than replaced by old settings.

Setting ownership and precedence

Setting or action Read/write behavior
Providers and model metadata Shared native provider_config.json
Default model in /settings Writes the shared default and applies it to the current session
/model, model cycling and reasoning effort Change/persist this session's native selection; shared default stays unchanged
/new Reads the current shared default
Resume/restart Restores the session's model and reasoning options
Language and memory Reads Desktop localePreference / memoryEnabled; explicit CLI settings override these values
Theme, terminal layout, copy-on-select and notifications CLI setting.json
Tool permissions, retries, stream timeout, CLI plugin/MCP options and other runtime settings CLI setting.json, with native project/environment precedence
Update cache, diagnostic logs and migration state Operational files beneath the CLI directory

The CLI does not add keys to Desktop's setting.json. Notification and display changes write only the CLI file. Shared preferences are applied while loading runtime settings, not copied into CLI settings during unrelated updates.

Model catalogs and default selection

The native registry loads the bundled catalog and manages upstream catalog refreshes. /model, model cycling, and Settings > Model providers refresh the current registry from its configuration sources. The session is retained. The CLI does not keep a separate legacy model catalog cache.

config.defaultModelSelection in the provider file chooses the model for new sessions. /settings saves that selection through the native repository and applies it to the current session. /model provider/model is a temporary session switch. A resumed session can retain its saved selection.

Reasoning options omitted from a saved selection are completed using that model's registry defaults. Explicit reasoning choices remain intact.

First-run setup

The setup wizard appears on the first interactive launch. Choose Sign in, Custom provider, or Skip for now. /setup reopens it. A setup-pending marker beside the general config survives non-interactive commands and is cleared after successful configuration or an explicit skip. An existing native provider configuration is recognized directly; no desktop import step is needed.

Model access

  • Z.AI OAuth on macOS: use zcode login, or zcode login --oauth to force authorization. --no-browser prints the authorization URL.
  • Z.AI/BigModel Coding Plan API key: open /login and choose the masked API-key option. The official runtime owns credential and provider persistence.
  • Custom provider: configure the native provider file directly. Any provider ID can be used; a separate OAuth login is unnecessary.

Plain zcode login recognizes a configured native default and reports its configuration path. Configuration presence is checked locally; credential validation and decryption belong to the runtime.

For macOS OAuth, the CLI temporarily registers a callback receiver, checks state, restores the previous zcode:// handler and sends the callback through stdin. The runtime exchanges the token, stores encrypted credentials, resolves the Coding Plan API key and saves the native default model. The TUI then rereads provider configuration. BigModel uses the runtime's localhost callback.

Custom provider

Use provider.example.json as a reference for a new provider file. Its enabled model inherits the upstream catalog; its disabled reference models demonstrate all smart-override and manual fields. Fill the empty API key, replace the placeholder IDs/endpoint, and remove unused reference entries. When a file already exists, merge the desired provider rule into it and preserve the other rules and selections.

A minimal configuration uses this structure:

{
  "schemaVersion": 1,
  "config": {
    "providerConfigRules": {
      "providerRules": [
        {
          "providerId": "custom",
          "providerName": "Custom provider",
          "config": {
            "group": "standard-personal",
            "access": { "type": "api-key", "apiKey": "YOUR_API_KEY" },
            "api": {
              "type": "openai-chat-completions",
              "baseUrl": "https://api.example.com/v1"
            },
            "personalModelIds": ["your-model-id"]
          }
        }
      ]
    },
    "modelConfigRules": {
      "providerModelRules": [],
      "manualProviderModelRules": []
    },
    "defaultModelSelection": {
      "providerId": "custom",
      "modelId": "your-model-id"
    }
  }
}

Use anthropic-messages for an Anthropic-compatible endpoint, openai-chat-completions for Chat Completions, or openai-responses for the Responses API. baseUrl is the API root; model IDs are case-sensitive. The model reference is providerId/modelId.

/model custom/your-model-id
/settings
/new

The native catalog supplies context limits, reasoning options and input/output capabilities for known models. Custom metadata overrides belong in the native modelConfigRules, including properties.contextWindow, properties.inputFormat and optionSpecs. Image, video and PDF support follow the selected model's registry metadata.

Use properties.supportsJsonSchemaOutput, supportsNativeWebSearch and supportsMidConversationSystem for Desktop's three capability switches. The maximum output limit is optionSpecs.maxOutputTokens.max; it is independent of the context window. Request parameter mappings belong in each option's map string. See the complete field tables and examples.

When the upstream catalog changes, smart models inherit the new capability and option metadata automatically. Only explicit personal overrides remain fixed. Runtime sync copies the complete catalog, and /model refreshes the live registry; there is no need to write upstream capability values into every personal model.

Permission and planning state

The CLI follows Desktop's three selectable permission modes: build (ask before changes), edit (edit automatically), and yolo (full access). /mode opens the picker; Shift+Tab cycles these three options. The internal auto value is not a menu option.

/plan toggles planning independently. /plan on and /plan off set it explicitly. Changing permissions keeps the Plan switch unchanged; toggling Plan keeps the selected permissions unchanged. The native runtime owns validation, including the restriction against enabling Plan while a Goal is active.

When enabled, Plan appears at the right end of the input's upper border without adding a row. An empty editor shows a planning hint. The statusline always shows the permission mode, and /status lists Mode and Plan separately. The marker follows native state changes, including plan approval, new sessions and resume; no separate CLI preference is written for Plan.

Prompt access preflight

New headless prompts and ordinary TUI input diagnose missing provider setup or an explicitly keyless API-key provider before a model turn starts. No key or credential value is printed or checked over the network. Account authentication, malformed configuration, environment overrides, project configuration and resumed headless sessions remain the runtime's responsibility.

The TUI restores rejected input to an empty editor, or retains it in the follow-up queue without replacing a newer draft. Headless commands exit with setup instructions. Login, setup and other management commands remain usable.

Background agents

Long-running Agent calls automatically detach from the foreground turn after one second and remain available through /tasks. Short Agent calls stay inline so the current response can use their result without a notification round trip. Configure the threshold in milliseconds:

{
  "subagents": {
    "autoBackgroundMs": 1000
  }
}

Set the value to 0 to disable automatic backgrounding. Agent tool calls that use run_in_background: true detach immediately regardless of this threshold.

Request retries and stalled streams

The CLI leaves retry classification and execution to the official ZCode runtime. It supplies a default retry budget of five retries; override it when needed with the runtime's own environment variable:

ZCODE_MODEL_RETRY_MAX_RETRIES=3 zcode

Newly generated configs use a 60-second model-stream idle timeout:

{
  "modelStream": {
    "idleTimeoutMs": 60000
  }
}

Existing configs are never overwritten, so update this field manually if an older generated file still contains 600000. Retryable timeouts, dropped streams, rate limits and server/network errors are retried and shown in the TUI. Authentication and invalid-request responses remain non-retryable.

Runtime diagnostics

The interactive TUI captures runtime stderr so background diagnostics cannot overwrite terminal rendering. A non-zero runtime exit prints its status and the diagnostic path after the TUI stops. The active log is capped at 2 MB and rotated to .1 on the next launch; both files use owner-only permissions.

The default path is ~/.zcode/cli/tui-runtime.log. Override it when collecting diagnostics in an isolated environment:

ZCODE_TUI_RUNTIME_LOG=/tmp/zcode-tui-runtime.log zcode

TUI display mode

The interactive TUI uses regular scrollback output by default. Set ui.tuiMode to "fullscreen" to use the terminal's alternate screen with an independently scrollable transcript, a fixed composer, and mouse-wheel/ scrollbar navigation. The composer remains available while older transcript content is being reviewed. The scrollbar is hidden when the transcript fits, then appears briefly while scrolling and follows the active dark/light theme.

{
  "ui": {
    "tuiMode": "fullscreen"
  }
}

The same setting can be changed from /settings (or /config) under Display mode. ZCODE_TUI_MODE=fullscreen or ZCODE_TUI_MODE=regular temporarily overrides the saved value for the current shell; the settings picker labels this override and does not remove it.

Fullscreen mode is restored on normal exit and on handled SIGINT, SIGTERM, or SIGHUP shutdowns. A hard SIGKILL cannot be intercepted by any terminal application.

Copy on select

Releasing a mouse selection in fullscreen mode copies the selected text to the system clipboard. Set ui.copyOnSelect to false to keep copying manual: drags then only highlight, and the terminal's native selection (hold Shift or the modifier your emulator documents while dragging) still works. The setting only affects fullscreen mode; regular scrollback mode has no mouse selection. The same toggle is available in /settings under Fullscreen copy on select.

{
  "ui": {
    "copyOnSelect": false
  }
}

Theme

Set ui.theme to "auto" (terminal detection), "dark", or "light" in the user config: ~/.zcode/cli/setting.json on macOS/Linux or %USERPROFILE%\.zcode\cli\setting.json on Windows. An explicit dark/light value takes priority over terminal probing. auto queries the terminal background color and color scheme at startup and re-applies the matching palette.

Turn completion notifications

Notifications are enabled by default and emitted after a normal agent turn completes or fails while the terminal is unfocused. Following Codex's terminal capability fallback, auto uses OSC 9 in Ghostty, iTerm2, Kitty, Warp and WezTerm, and BEL in terminals such as Apple Terminal. Selecting OSC 9 in an unsupported terminal also falls back to BEL instead of silently emitting an ignored sequence.

The unfocused condition uses DEC focus reporting when the terminal provides it. Until focus support is confirmed, ZCode sends the notification instead of permanently suppressing it as focused. native is an explicit opt-in that uses an existing system command: terminal-notifier on macOS, notify-send on Linux, or SnoreToast on Windows. These tools are not bundled, keeping the default terminal notification path dependency-free. If the selected command is unavailable or delivery fails, ZCode falls back to BEL. On macOS, the detected terminal application is used as both the sender and click target. Exact tab or pane restoration remains terminal-dependent; use the default auto setting so OSC-capable terminals can preserve their native session behavior.

Open the interactive settings picker inside the TUI (both commands are equivalent):

/config
/settings

Saving a value returns to the settings root so several options can be changed in one visit. Esc returns from a setting to the root, then closes the root.

The picker updates the active session immediately and persists the selected values under ui.notifications in the cross-platform user setting.json:

{
  "ui": {
    "notifications": {
      "method": "auto",
      "condition": "unfocused"
    }
  }
}

Environment variables override setting.json on startup and are useful for a temporary per-shell setting:

export ZCODE_TUI_NOTIFICATION_METHOD=auto       # auto|osc9|bel|native|off
export ZCODE_TUI_NOTIFICATION_CONDITION=always  # unfocused|always
zcode

Official MCP Availability

When the bundled runtime has no official MCP trusted-origin registry, official HTTP MCP services are reported as disabled with an official_auth_unavailable diagnostic. Other plugin components remain available. This does not disable certificate, origin, or permission checks, and does not suppress services when the runtime provides the required registry. No user configuration is rewritten.