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

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
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
Save Configuration
- Stores the updated settings
- Applies preferences to subsequent CLI runs
- Uses environment overrides when present

Diff Tools by Platform

Windows
- Visual Studio Code
- Beyond Compare
- Hunk
- WinMerge
- Araxis Merge
- DiffMerge
- TortoiseMerge
- P4Merge
- Other (prompts for a custom command when comparison starts)
- None
macOS
- Visual Studio Code
- Beyond Compare
- Hunk
- FileMerge
- Araxis Merge
- DiffMerge
- Kaleidoscope
- P4Merge
- Other (prompts for a custom command when comparison starts)
- None
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.
Hunk 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.
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