LinkCattle CLI

Install and upgrade

Use the verified installation command on the homepage for installation and upgrades. It prepares independent Node/npm and migrates known old command entries. After installation, start the background service:

linkcattle service install

service install selects and verifies this package's platform payload, installs the Runtime and starts the user background service. It also works when npm skips installation scripts; no script approvals or npm rebuild are required. On macOS, it checks Runtime readiness and reports any required system approval. Finish active tasks before upgrading.

Advanced npm users can use npm install -g linkcattle with an external Node and writable prefix. If another old command shadows it, use the homepage installer to migrate known entries. App-bundled Node/npm remains blocked; keep system security protections enabled.

If macOS requires approval for the background service, follow the reported System Settings prompt; registration alone does not mean it is running. Installation does not request Screen Recording, Accessibility/input or camera access. Those permissions remain separate and require your explicit approval when needed.

Connect

linkcattle --lang en
linkcattle --region cn
linkcattle login
linkcattle connect codex
linkcattle connect pi --executable /absolute/path/to/pi
linkcattle connect claude --profile /absolute/private/claude/profile.json
linkcattle connect dsh --profile /absolute/private/deepseek/profile.json
linkcattle connect web 127.0.0.1:8080 --name Workbench
linkcattle connect web 'http://127.0.0.1:8080/workspace?view=code#session=example'
linkcattle connect file
linkcattle connect file /absolute/shared/folder
linkcattle connect api 127.0.0.1:9000 --routes /absolute/api-routes.json

All connect commands accept -qr for phone claiming. Omit it when signed in to claim directly. No project is bound by default; add --workspace /absolute/project when needed. Pi may use --agent-dir for its existing authentication directory. DSH means DeepSeek Harness. Each agent keeps its own model login, tool permissions and approvals; LinkCattle does not turn it into a Codex sandbox.

Phone and email verification are available. linkcattle login --mode browser|terminal selects a mode; macOS/Windows default to the browser, SSH/CI or missing browsers fall back to the terminal, and Linux defaults to the terminal. A valid browser session skips another code. --phone, --email and --stdin use the terminal; stdin accepts {phone,code} or {email,code}. Phone and email accounts are not automatically merged. See account login.

Website connections preserve the opening path, query and fragment while forwarding to the same fixed loopback HTTP origin. Quote URLs containing shell metacharacters. Reconnecting the same origin preserves its service identity and updates its opening URL. Private query and fragment values stay in protected local configuration and the encrypted browser handshake; connection lists show only the origin.

File connections without a directory use the host filesystem root (Unix /, Windows host drive/UNC root) and do not start an agent. Specify a directory to limit the scope. Install File manager through the signed marketplace to browse the selected directory, upload documents and download files or ZIP folders. files.read and files.write separately control access. Paths and symlinks cannot escape the selected directory; protected credentials and tool sign-ins are excluded. Use the matching runtime and signed File App packages.

Codex desktop sharing supports macOS only. Before first connection, finish tasks and quit independently running Codex. Reopen it normally after connecting; no daily shared-control launcher is required. Background startup honors enabled macOS system proxies, with existing proxy environment variables taking precedence.

Emergency Mac desktop

On macOS, native permissions belong to ~/Applications/LinkCattle Runtime.app, used by the CLI. The independent macOS ARM64 Core 0.1.1 release has passed Developer ID signing, Apple notarization and Gatekeeper. CLI platform components require their own signing and notarization acceptance. When an upgrade reports access needs setup, review linkcattle permissions status and explicitly open setup; capture, input and camera remain denied until granted.

The macOS ARM64 CLI package includes the Runtime and emergency desktop adapter. On the Mac being controlled, request access locally and connect:

linkcattle permissions status
linkcattle permissions setup
linkcattle connect remote

Approve Screen Recording and Accessibility for LinkCattle Runtime in macOS System Settings, then install the matching signed Emergency desktop App through the marketplace in the Android App. Viewing requires desktop.view; mouse and keyboard control also require desktop.control and an explicit Enable control action. Screen access covers the current Mac login's primary display, including other applications. The App cannot grant system permissions or authorize an Agent to control the desktop.

Keep macOS 14+ awake, logged in and online. Disconnects release input and reconnects do not replay it. Capture and transfer capabilities depend on the matching Runtime and App. Login screens and unattended startup remain separate from the active desktop session. Custom adapters follow the maintained adapter guide and the same installed Runtime permission boundary.

Qoder

Qoder CLI 1.1.37 uses its own sign-in. With Node.js 22+, npm and jq installed, the first connection prepares its SDK automatically:

linkcattle connect qoder

Use a matching Connector and Coding App that declare relay.qoder. Qoder keeps its official local sign-in; its profile must not contain a model key or custom endpoint. IDE shared control is unavailable.

Manage connections

linkcattle status
linkcattle list
linkcattle disconnect ID
linkcattle service status
linkcattle service restart
linkcattle service uninstall
linkcattle delete INSTANCE_ID --yes

The CLI uses one user background service. Closing a terminal or window leaves it running. Sleep, network loss or a stopped business application makes the service unavailable. disconnect pauses a connection; uninstalling the background service retains configuration. delete permanently removes service registration and sharing grants, retaining projects, native sessions and computer files.

For repair, check linkcattle service status first. linkcattle service install remains available when the reported state requires installation repair; it does not replace required system approval or grant capture, input or camera permissions.

The current Linux source verifies systemd lingering for the installing user, including root, during installation and restart. This keeps the user service alive after the last SSH logout and starts it at boot. If the system refuses the change, setup reports loginctl enable-linger <uid> and fails instead of claiming persistence. WSL itself must remain running. Uninstall leaves the user's linger setting unchanged because other user services may rely on it.

Use linkcattle service restart for permissions that require a restart. Finish active tasks before restarting: remote access briefly disconnects, then enabled connections recover. Accounts, service registrations, project files and agent sessions are preserved. The command checks that a new background process is ready before reporting success; it does not grant system permissions. If background access is awaiting approval, approve it in System Settings first.

API access

The route file declares a business contract and explicit capabilities:

{
  "business_api": {"id": "example.api", "version": "1.0.0"},
  "routes": [
    {"methods": ["GET"], "path": "/health", "requires": ["api.read"]},
    {"methods": ["POST"], "path": "/jobs", "requires": ["api.write"]}
  ]
}

The upstream is fixed to a loopback HTTP origin. HTTP/SSE keep business paths; WebSocket routes require websocket: true. Unknown routes and missing capabilities are rejected. Changing the permission file creates a new instance; pause the old one explicitly.

linkcattle access INSTANCE_ID --capabilities api.read --output /absolute/private/access.json

The mode-600 file contains a short-lived endpoint and access_token; requests use Relay-Authorization: Bearer <access_token>. Never print, commit or share this file. Create a new file after expiry; existing files are not overwritten. See the online developer guide for stream handling and App integration.

Platforms, region and language

Payloads support macOS ARM64 and Linux x64; installation selects the platform and verifies its hash. Linux targets Ubuntu 24.04 / glibc 2.39 and needs user-level systemd. Binaries/installers were checked in containers; real user-systemd startup remains unverified. Windows uses WSL 2 / Ubuntu 24.04 and is not verified on a real machine. Native Windows, Linux ARM64 and musl have no payload. Use Pi, Claude or DSH on Linux/WSL.

China is the available account region. Singapore and US require their own configured endpoints; switching regions does not migrate accounts or services. linkcattle --lang zh|en|ja|ru saves a preference; LINKCATTLE_LANG overrides the current process. Language does not change region.

CLI uses ~/.linkcattle/. Keep configuration and credentials protected, and never package private data. Platform login and agent model login are separate.

Send a file or website to your phone

linkcattle send /absolute/path/report.pptx --expires 30m --name "Report" --json
linkcattle connect web http://127.0.0.1:3000 --expires 30m --notify --name "Preview" --json

send creates a 30-minute delivery by default; --expires accepts s, m, or h, from 60 seconds to 24 hours. Temporary connections have independent identities and do not change existing permanent connections. The selected file stays on the computer and its parent directory is not exposed. Keep the computer awake, online and running LinkCattle; website previews also need the local website process. Expiry closes remote access, including after a background-service restart. Files already downloaded remain on the receiving device.

The response includes notification_id, an account-bound linkcattle://notifications/... link and expires_at. Open the notification in LinkCattle using the same account. It is not an anonymous public URL. notification_error means delivery must be checked in the inbox; do not blindly create another connection. A queued notification is not proof of phone delivery.

When connecting a Coding agent interactively, choose whether to install the LinkCattle delivery skill. Noninteractive calls never install it implicitly:

linkcattle connect codex --install-skill
linkcattle connect pi --no-install-skill

Installation affects only the selected agent's skill directory, preserves different existing skill content, and does not change its model sign-in or permissions. The skill responds to requests such as “send this with kitty”. Existing sessions may need their normal skill reload or a new turn to discover it.

0.1.0 release scope

LinkCattle 0.1.0 retains disclosed Coding limits: Claude and Qoder cannot receive additional instructions within the same native turn; tool approvals for Pi, Claude, DSH and Qoder do not provide OS isolation. Independent official desktop or IDE sessions cannot be fully taken over, and external native session management has gaps. Qoder real-account/model-control and physical-phone acceptance remain pending.