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

# 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