zag-cli 0.8.0

A unified CLI for AI coding agents — Claude, Codex, Gemini, Copilot, and Ollama
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81

# zag connect

Connect to a remote zag server.

## Synopsis

    zag connect <url> [flags]

## Description

Connects to a remote zag server and saves the connection configuration. Once connected, all subsequent zag commands transparently proxy through the remote server until `zag disconnect` is called.

If the URL does not include a scheme, `https://` is automatically prepended.

The connection state is stored in `~/.zag/connect.json`. While connected, commands like `zag spawn`, `zag status`, `zag listen`, `zag session list`, and others are forwarded to the remote server's REST/WebSocket API.

## Arguments

    url    Server URL (e.g., home.local:2100 or https://home.local:2100)

## Flags

    --token <TOKEN>    Authentication token (or set ZAG_CONNECT_TOKEN env var)

## Health Check

Before proxying each command, zag pings the remote server's health endpoint to verify it is reachable. If the server is unreachable, zag automatically disconnects and runs the command locally, printing a warning to stderr. The health check result is cached for 30 seconds to avoid adding latency on every invocation.

To disable this behavior, use the `--no-health-check` global flag or set the `ZAG_NO_HEALTH_CHECK=1` environment variable:

    zag --no-health-check status <session-id>

## Commands That Work Remotely

    zag spawn          Spawn a session on the remote machine
    zag status         Check session status
    zag events         Query session events
    zag listen         Stream session events in real-time (via WebSocket)
    zag subscribe      Subscribe to all session events
    zag cancel         Cancel a session
    zag collect        Collect results
    zag wait           Wait for sessions to complete
    zag output         Get session output
    zag session list   List sessions
    zag session show   Show session details
    zag ps             List processes
    zag input          Send a message to a session

## Commands That Always Run Locally

    zag serve          Start a local server
    zag connect        Connect to a server
    zag disconnect     Disconnect from a server
    zag run            Interactive sessions (local only)
    zag exec           Non-interactive execution (local only)
    zag config         Local configuration

## Examples

    # Connect to a remote server (https:// auto-prepended)
    zag connect home.local:2100 --token mysecrettoken

    # Connect with explicit scheme
    zag connect https://home.local:2100 --token mysecrettoken

    # Now all commands proxy through the remote server
    zag spawn "write tests for auth module"
    zag listen --latest
    zag session list

    # Spawn an interactive session on the remote machine
    sid=$(zag spawn --interactive --name worker -p claude)
    zag input --name worker "analyze the auth module"
    zag listen --name worker

    # Disconnect when done
    zag disconnect

## See Also

`zag serve`, `zag disconnect`