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

# Link Instance

The `link` command connects your local application to a ZeyOS instance and sets up synchronization.

```bash
zeysdk link [INSTANCE_ID] [options]
```

**Parameters**

| Parameter | Description | Required | Example |
|-----------|-------------|----------|---------|
| `INSTANCE_ID` | ZeyOS instance identifier | No | `myinstance` |

**Options**

| Option | Description |
|--------|-------------|
| `--token <token>` | SDK authentication token |
| `--url <url>` | Instance URL |
| `--break-lock` | Replace the current sync lock after you verify its operation is no longer running |
| `--verbose` | Show detailed output |

**Process**

1. **Connection Setup**
   - Requires the current directory to contain `zeyos.app.json` with `identifier` and `name`
   - Resolves the instance ID, URL, and token from arguments, environment variables, saved hosts, or prompts
   - Defaults the URL to `https://cloud.zeyos.com/<INSTANCE_ID>`
   - Can infer a missing instance ID from the server URL

2. **Authentication**
   - Validates the SDK token
   - Fetches the remote application, or creates it when it does not yet exist
   - Saves credentials only after the link operation succeeds
   - During an expired-token relink, validates the new token before replacing the saved credential; an obsolete URL-keyed entry is removed afterward

3. **Sync Setup**
   - Creates or updates `.zeysdk/sync.json`
   - Keeps the active link in `.zeysdk/sync.json` and other linked instances in `.zeysdk/sync.<INSTANCE_ID>.json`
   - Creates `settings/settings.<INSTANCE_ID>.json` when absent
   - Makes the newly linked instance active
   - Restores those local files if link setup fails
   - Holds the shared operation lock through remote validation, local state changes, and credential persistence
   - Makes the instance available for push, pull, sync, and activity commands

**Examples**

```bash
zeysdk link myinstance
zeysdk link myinstance --url https://custom.domain/app
zeysdk link myinstance --token "$ZEYSDK_TOKEN" --url https://cloud.zeyos.com/myinstance --verbose

# The same values can be provided by the environment
ZEYSDK_TOKEN=abc123 ZEYSDK_SERVER=https://cloud.zeyos.com/myinstance zeysdk link myinstance
```

**Error Handling**

| Error | Description | Resolution |
|-------|-------------|------------|
| Missing token | No SDK token provided | Enter a token when prompted or use `--token` |
| Invalid instance | Instance ID contains unsupported characters | Use letters, numbers, dots, underscores, and hyphens, beginning and ending with a letter or number |
| Invalid URL | Instance URL cannot be reached | Check `--url` or instance ID |
| Auth failed | Invalid token | Generate a new SDK token |
| Save failed | Sync configuration could not be written | Check local permissions |

**Notes**

- `INSTANCE_ID` can be provided as an argument or resolved interactively
- `--url` overrides the default cloud URL for the instance
- Command-line flags take precedence over `ZEYSDK_TOKEN` and `ZEYSDK_SERVER`
- Pass both token and URL for predictable non-interactive setup unless a matching saved host supplies the missing value
- Unlike `zeysdk clone`, a normal link creates the remote application if it is missing
- Linking does not automatically push local files
- If the remote app is created and a later local write fails, local files are rolled back but the remote creation is not automatically undone

**Best Practices**

- Link development and production instances with clear IDs
- Use `zeysdk whoami` after linking to verify the active instance
- Avoid sharing SDK tokens in shell history when possible
- Run `zeysdk compare` before the first push to an existing remote app