zag-cli 0.8.3

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
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119

# zag session

List and inspect sessions.

## Synopsis

    zag session <command> [options]

## Description

Manage and inspect agent sessions tracked in `~/.zag/projects/<sanitized-path>/sessions.json`.

Sessions are automatically created when running agents with `zag run` or `zag exec`. This command provides read access to session history and the ability to import historical provider logs.

## Commands

### list

List all sessions, sorted by creation time (newest first).

    zag session list [--json] [-p provider] [-n limit] [--global] [--name NAME] [--tag TAG] [--parent SESSION_ID]

Options:
- `--json` — Output as JSON array
- `-p, --provider` — Filter by provider name (e.g., claude, codex, gemini)
- `-n, --limit` — Show only the N most recent sessions
- `--global` — List sessions across all projects (not just the current one)
- `--name` — Filter by session name (case-insensitive substring match)
- `--tag` — Filter by tag (case-insensitive exact match)
- `--parent` — Show only sessions spawned by this parent session ID

### show

Show details of a specific session.

    zag session show <id> [--json]

Options:
- `--json` — Output as JSON object

The `<id>` can be either the wrapper session ID or the provider-native session ID.

### delete

Delete a session from the store.

    zag session delete <id> [--json]

Options:
- `--json` — Output as JSON object

The session entry is removed from the store. Associated log files on disk are not deleted.

### update

Update session metadata (name, description, tags).

    zag session update <id> [--name NAME] [--description TEXT] [--tag TAG ...] [--clear-tags]

Options:
- `--name` — Set the session name
- `--description` — Set the session description
- `--tag` — Add a tag (repeatable)
- `--clear-tags` — Clear all existing tags before adding new ones

Only provided fields are updated; omitted fields remain unchanged.

### import

Import historical provider logs into the session store. Previously imported sessions are skipped.

    zag session import

Supported providers: Claude, Codex, Gemini, Copilot, Ollama (no-op today).

## Examples

    # List all sessions
    zag session list

    # List sessions as JSON
    zag session list --json

    # List only Claude sessions
    zag session list -p claude

    # Show the 5 most recent sessions
    zag session list -n 5

    # List sessions across all projects
    zag session list --global

    # Filter by session name
    zag session list --name frontend

    # Filter by tag
    zag session list --tag backend

    # Update session metadata
    zag session update abc123-def456 --name "my-agent" --tag backend
    zag session update abc123-def456 --clear-tags --tag new-tag

    # Show details of a specific session
    zag session show abc123-def456

    # Show session details as JSON
    zag session show abc123-def456 --json

    # Delete a session
    zag session delete abc123-def456

    # Import historical provider logs
    zag session import

## See Also

    zag man listen    Tail a session's log events in real-time
    zag man run       Resume a specific session with --resume
    zag man zag       Global flags and providers overview