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