Skip to content

clinvk sessions

Manage sessions.

Synopsis

clinvk sessions [command] [flags]

Description

The sessions command provides subcommands for managing clinvk sessions. Sessions store conversation history and state, allowing you to resume conversations later.

Subcommands

Command Description
list List all sessions
show Show session details
delete Delete a session
clean Remove old sessions
tag Add or remove session tags

clinvk sessions list

List all sessions.

Flags

Flag Short Type Default Description
--backend -b string Filter by backend
--status string Filter by status (active, completed, error, paused)
--tag string Filter by tag
--search string Search by id, title, or initial_prompt
--limit -n int Max sessions to show
--offset int 0 Skip this many sessions before returning results
--json bool false Output machine-readable JSON

Examples

List all sessions:

clinvk sessions list

Filter by backend:

clinvk sessions list --backend claude

Filter by status:

clinvk sessions list --status active

Limit results:

clinvk sessions list --limit 10

Combined filters:

clinvk sessions list --backend claude --status active --tag urgent --limit 5

Search and filter:

clinvk sessions list --search "auth bug" --tag urgent --json

Paginated JSON:

clinvk sessions list --backend claude --limit 10 --offset 20 --json

Output

ID        BACKEND   STATUS     LAST USED       TOKENS       TITLE/PROMPT
abc123    claude    active     5 minutes ago   1234         fix the bug in auth.go
def456    codex     completed  2 hours ago     5678         implement user registration
ghi789    gemini    error      1 day ago       -            failed task

JSON output:

{
  "items": [
    {
      "id": "abc123...",
      "backend": "claude",
      "status": "active",
      "last_used": "2026-02-15T01:02:03Z",
      "model": "claude-opus-4-5-20251101",
      "tags": ["feature-auth"],
      "title": "fix auth bug",
      "prompt_preview": "fix the bug in auth.go"
    }
  ],
  "total": 42,
  "limit": 10,
  "offset": 20,
  "filters": {
    "backend": "claude",
    "status": "",
    "tag": "feature-auth",
    "query": "auth bug"
  },
  "sort": {
    "by": "last_used",
    "order": "desc"
  }
}

clinvk sessions show

Show details of a specific session.

Usage

clinvk sessions show <session-id> [flags]

Flags

Flag Type Default Description
--json bool false Output session details as machine-readable JSON

Example

clinvk sessions show abc123

Show JSON details:

clinvk sessions show abc123 --json

Output

ID:                abc123
Backend:           claude
Model:             claude-opus-4-5-20251101
Status:            active
Created:           2025-01-27T10:00:00Z
Last Used:         2025-01-27T11:30:00Z (30 minutes ago)
Working Directory: /projects/myapp
Backend Session:   session-xyz
Turns:             3
Token Usage:
  Input:           1234
  Output:          5678
  Total:           6912
Tags:              [feature-auth, urgent]

clinvk sessions delete

Delete a specific session.

Usage

clinvk sessions delete <session-id>

Example

clinvk sessions delete abc123

Output

Session abc123 deleted.

clinvk sessions clean

Remove old sessions.

Flags

Flag Type Default Description
--older-than string Delete sessions older than this many days (e.g. 30 or 30d)
--dry-run bool false Preview cleanup candidates without deleting data

If not specified, uses the session.retention_days config value.

Examples

Clean sessions older than 30 days:

clinvk sessions clean --older-than 30d

Clean sessions older than 7 days:

clinvk sessions clean --older-than 7

Use config default:

clinvk sessions clean

Preview cleanup without deleting:

clinvk sessions clean --older-than 30d --dry-run

Output

Deleted 15 session(s) older than 30 days.

Dry run output:

Dry run: would delete 15 session(s) older than 30 days.
Sample session IDs: abc123..., def456...
No sessions were deleted. Re-run without --dry-run to apply.
Note: candidate sessions may change between dry-run and actual cleanup.

clinvk sessions tag

Add or remove tags for a session.

Subcommands

Command Description
tag add <session-id> <tag> [tag...] Add one or more tags
tag rm <session-id> <tag> [tag...] Remove one or more tags

Flags

Flag Type Default Description
--dry-run bool false Preview tag changes without saving

Examples

Add tags:

clinvk sessions tag add abc123 urgent feature-auth

Remove tag:

clinvk sessions tag rm abc123 urgent

Preview removal:

clinvk sessions tag rm abc123 urgent --dry-run

Output

Applied 2 tag change(s) on session abc123...
Current tags: urgent, feature-auth

Dry run output:

Dry run: would remove 1 tag change(s) on session abc123...
Requested tags: urgent
No session data was modified.

Session Status

Status Description
active Session is active and can be resumed
completed Session completed normally
error Session ended with an error
paused Session is paused (not currently active)

Common Errors

Error Cause Solution
session not found Session ID doesn't exist Check clinvk sessions list
invalid status filter Unknown status value Use active, completed, error, or paused
no sessions to clean No sessions match criteria Adjust filters or retention period

Exit Codes

Code Description
0 Success
1 Error (e.g., session not found)
4 Session error

See Also