Authentication

The SDK accepts credentials from environment variables or from its saved host store. A local app link records the active instance in .zeysdk, while saved host credentials are global to the user account.

1. Environment Variables (Recommended for CI/CD)

Environment variables are the recommended method for CI/CD environments and automated workflows.

Bash

# Set environment variables
ZEYSDK_TOKEN=your_token
ZEYSDK_SERVER=https://cloud.zeyos.com/your_instance

# Run commands
zeysdk [command]

ZEYSDK_TOKEN overrides token lookup. ZEYSDK_SERVER overrides the active sync URL for commands that load sync data, including run and compile, and is also consumed by zeysdk link. Set both for portable non-interactive execution; a server-only override still needs a matching saved token for the active instance and URL.

Platform-Specific Commands

Windows CMD:

CMD

set ZEYSDK_TOKEN=your_token && set ZEYSDK_SERVER=https://cloud.zeyos.com/your_instance && zeysdk [command]

Windows PowerShell:

PowerShell

$env:ZEYSDK_TOKEN="your_token"; $env:ZEYSDK_SERVER="https://cloud.zeyos.com/your_instance"; zeysdk [command]

Linux/macOS:

Bash

export ZEYSDK_TOKEN=your_token && export ZEYSDK_SERVER=https://cloud.zeyos.com/your_instance && zeysdk [command]

2. Stored Credentials (Default for local development)

For local development, link an application once and let the SDK reuse the saved instance-and-URL credential.

Bash

# Link your instance first
zeysdk link

# Then run commands
zeysdk [command]

Authentication and URL Priority

For zeysdk link, explicit --token and --url flags take precedence over ZEYSDK_TOKEN and ZEYSDK_SERVER. The resulting values then take precedence over a saved host or an interactive prompt.

For commands operating on an existing link:

1. A non-empty ZEYSDK_SERVER replaces the URL from .zeysdk/sync.json.
2. A non-empty ZEYSDK_TOKEN replaces the saved token.
3. Without ZEYSDK_TOKEN, the SDK looks up a saved credential for the active instance and effective URL. Legacy instance-only entries are used only when their stored URL matches the effective URL; otherwise relink the instance or provide explicit environment credentials.

zeysdk bundle install deliberately requires --token and --url together when either flag is used.

Credential Storage

Choose the backend interactively with zeysdk configure → Credential Storage:

Mode	Behavior
Auto	Uses the OS keyring on supported desktop systems. WSL and headless Linux use the file store; an unavailable desktop keyring may also fall back to it.
OS Keyring	Requires the platform keyring and reports an error when it cannot be used.
File Store	Stores credentials unencrypted in ~/.config/zeysdk/store.json with owner-only file permissions.

The storage preference is written to ~/.config/zeysdk/settings.json. When the keyring is used, ~/.config/zeysdk/account-index.json tracks account names so the CLI can enumerate configured hosts; tokens remain in the keyring.

ZEYSDK_USE_KEYRING overrides the saved mode. Values 1, true, or yes select the keyring; other values select the file store. ZEYSDK_USE_KEYTAR is accepted as a legacy alias when the newer variable is unset.

Expired Tokens

When most wrapped commands receive a 401, the CLI can prompt once for a replacement token, validate the relink, update the saved credential, and retry the original command once. link reports its own authentication failure instead of recursively relinking, and migrate does not perform the automatic retry.

Security Notes

• Stored credentials can use the OS keyring or the unencrypted file store
• Environment-variable lifetime depends on how the shell or CI system defines them
• Stored credentials persist between sessions
• Use environment variables for CI/CD to avoid storing credentials
• Use stored credentials for local development convenience
• Avoid putting tokens directly into shared scripts, command history, logs, or bundle files

Error Handling

Error	Description	Resolution
Missing token	No authentication provided for the active instance and effective URL	Set both environment variables, add a matching host, or run zeysdk link
Invalid token	Bad credentials	Check token validity
Server error	Invalid server URL	Verify server URL format
Keyring unavailable	Explicit keyring backend cannot be opened	Repair keyring access or select Auto/File Store
Network error	Connection failed	Check connectivity