Host Commands

The host command manages saved ZeyOS instance hosts.

Bash

zeysdk host <COMMAND> [options]

Available Commands

Command	Description
list	List all configured hosts
add [HOST_NAME]	Add a new host
update [HOST_NAME]	Update existing host
remove [HOST_NAME]	Remove host configuration
link [HOST_NAME]	Link current app to host

Options for add and update

Option	Description
-u, --url <url>	URL for the host
-t, --token <token>	Authentication token

Process

1. Host Listing

   • Reads saved host credentials
   • Displays configured host names and custom URLs; standard cloud.zeyos.com URLs are omitted from the compact listing
   • Hides stored tokens from output

2. Host Creation and Updates

   • Accepts host name, URL, and token from flags or prompts
   • Validates required values
   • Normalizes URLs by removing trailing slashes
   • Refuses to add a second entry with the same host name
   • Preserves the current URL or token when only the other field is supplied to update
   • Keeps the exact saved URL selected in interactive update, removal, and linking prompts
   • Rejects ambiguous positional host names before changes; omit the host name to choose the exact URL
   • Refuses to move an entry onto another saved credential for the same host and URL
   • Writes an updated URL-keyed credential before removing the old key; if old-key cleanup fails, it attempts to remove the replacement and keeps the known-good entry

3. Host Removal and Linking

   • Always asks for confirmation before removing saved credentials
   • Links the current app to a saved host when using host link
   • Requires app context for app-linking operations

Examples

Bash

# List all hosts
zeysdk host list
# Output: Configured hosts:
#         - instance1
#         - custom     https://zeyos.example.com/custom

# Add new host with options
zeysdk host add myinstance -u https://cloud.zeyos.com/app -t mytoken

# Add new host interactively
zeysdk host add
# Output: Enter the host name: myinstance
#         Enter the URL: https://cloud.zeyos.com/app
#         Enter the token: ****

# Update host with options
zeysdk host update myinstance --url https://cloud.zeyos.com/newapp
zeysdk host update myinstance --token replacement-token

# Update host interactively
zeysdk host update
# Output: Select a host to update:
#         > instance1
#         > instance2

# Remove host
zeysdk host remove myinstance

# Link the current app with a saved host
zeysdk host link myinstance

Error Handling

Error	Description	Resolution
Host exists	Duplicate host	Update existing host
Not in app	Outside app directory	Navigate to app directory for link command
Write error	Cannot save config	Check permissions
Host not found	Invalid host name	Check host name
Multiple saved URLs	Host name matches more than one saved endpoint	Omit the host name and select the exact URL interactively
Destination exists	Updating a URL would replace another saved credential	Select that destination entry to update its token
Link/auth error	Saved URL or token cannot link the app	Update the host and retry host link

Notes

• The link command is only available when inside a ZeyOS app directory
• host add and host update save values without making a network request; host link performs connection validation
• host add defaults a missing URL to https://cloud.zeyos.com/<HOST_NAME>; host link follows normal link behavior and can create the remote app when it is missing
• host remove has no force or --yes option
• Storage follows the configured credential backend: the OS keyring when selected and available, or the unencrypted local file store

Best Practices

• Use clear host names such as dev, staging, or prod
• Keep production tokens separate from development tokens
• Rotate tokens when team access changes
• Verify the host URL before linking an application