---
title: "Configure Application"
description: "Documentation for Configure Application Command in ZeyOS SDK CLI"
canonical_url: "https://www.zeyos.com/sdk/application-management/zeysdk-configure"
markdown_url: "https://www.zeyos.com/ai/guide/sdk/application-management/zeysdk-configure.md"
section: "sdk"
authority: "guide"
language: "en"
source_repository: "zeyos/sdk-v2"
source_path: "docs/application-management/zeysdk-configure.md"
source_revision: "a99897af74253b4dc5af6fecb9301cea0ae18e27"
---

# Configure Application

The `configure` command configures global CLI settings and preferences interactively.

```bash
zeysdk configure
```

**Available Settings**

| Setting | Description | Default |
|---------|-------------|---------|
| `Default Diff Tool` | Choose comparison tool for file diffs | Platform dependent |
| `List Height` | Number of items shown in selection lists | 10 |
| `Run Output Style` | Default output format for `zeysdk run` (`Pretty` or `Simple`) | Pretty |
| `Credential Storage` | Select credential backend (`Auto`, `OS Keyring`, `File Store`) | Auto |

**Process**

1. **Settings Prompt**
   - Opens interactive prompts for global CLI preferences
   - Shows platform-specific diff tool choices
   - Validates numeric settings such as list height
   - Press Escape in a setting screen to return to the settings menu without saving that selection
   - Press Escape or choose Back in the settings menu to exit without saving
   - Returning from a setting keeps that row selected

2. **Credential Backend Selection**
   - Lets you choose automatic storage, OS keyring, or file store
   - Uses the selected backend for future saved credentials
   - Persists the preference for later commands

3. **Save Configuration**
   - Stores the updated settings
   - Applies preferences to subsequent CLI runs
   - Uses environment overrides when present

**Diff Tools by Platform**

1. **Windows**
   - Visual Studio Code
   - Beyond Compare
   - Hunk
   - WinMerge
   - Araxis Merge
   - DiffMerge
   - TortoiseMerge
   - P4Merge
   - Other (prompts for a custom command when comparison starts)
   - None

2. **macOS**
   - Visual Studio Code
   - Beyond Compare
   - Hunk
   - FileMerge
   - Araxis Merge
   - DiffMerge
   - Kaleidoscope
   - P4Merge
   - Other (prompts for a custom command when comparison starts)
   - None

3. **Linux**
   - Visual Studio Code
   - Hunk
   - Meld
   - KDiff3
   - Kompare
   - Diffuse
   - xxdiff
   - P4Merge
   - Other (prompts for a custom command when comparison starts)
   - None

**Diff Tool Setup**

- Install the selected tool separately and make its command available on `PATH`.
- Beyond Compare uses `bcomp` on macOS and `BComp.com` on Windows. These launchers wait until the comparison closes, keeping the remote temporary file available. On macOS, use Beyond Compare's **Install Command Line Tools** menu item if `bcomp` is unavailable. See the [Beyond Compare command-line reference](https://www.scootersoftware.com/v5help/command_line_reference.html).
- [Hunk](https://www.hunk.dev) is available on all three platforms. Once its `hunk` command is installed, select **Default Diff Tool → Hunk**. ZeySDK runs `hunk diff --files` in the current terminal and waits for it to exit. See [Hunk's file comparison guide](https://www.hunk.dev/docs/workflows/files-and-patches/).
- Hunk provides a diff viewer. During a sync conflict, edit the local file in your editor before confirming that the merge is finished.
- Custom commands should wait for the comparison to finish before exiting; add the tool's wait flag where available.

**Configuration Storage**

General CLI settings are saved through the credential backend. The credential-storage preference itself is saved in `~/.config/zeysdk/settings.json`.

- `Auto`: Tries the OS keyring on supported desktop systems and falls back to the local file store; WSL and headless Linux select the file store directly
- `OS Keyring`: Uses platform keychain when available
- `File Store`: Stores credentials unencrypted in `~/.config/zeysdk/store.json` with owner-only file permissions

Environment variables (`ZEYSDK_USE_KEYRING` or legacy `ZEYSDK_USE_KEYTAR`) override configured storage mode.

**Error Handling**

| Error | Description | Resolution |
|-------|-------------|------------|
| Storage access | Failed to access configured credential backend | Check keychain availability or switch to File Store |
| Invalid saved configuration | Saved data is malformed JSON or is not a JSON object | Correct the saved value through the configured credential backend; the command leaves it unchanged |
| Invalid input | Invalid list height value | Enter a positive number |
| Save failed | Failed to save configuration | Verify write permissions |

**Notes**

- Configuration is global, not per application
- Diff tool selection affects compare and merge workflows
- `File Store` is useful in environments without OS keyring support
- Selecting `OS Keyring` explicitly fails if keyring access is unavailable; `Auto` may fall back
- Environment variables take precedence over saved credential storage settings

**Best Practices**

- Prefer `Auto` credential storage on developer workstations
- Use a diff tool that can be launched from the command line
- Keep list height high enough for projects with many instances or snapshots
- Use file store only when keyring access is unavailable or unsuitable