CLI: Sessions

Manage sessions and organize work with the Trix CLI.

Updated Oct 6, 2026

Overview

The trix session command provides a complete interface for managing sessions. Use sessions to organize work, track conversations, and maintain context across related memories.

Aliases: session, sess, s

# Quick reference
trix session create <name>      # Create new session
trix session list                # List all sessions
trix session switch <id|name>   # Switch to session
trix session pause               # Pause current session
trix session complete            # Complete current session

trix session create

Create a new session with optional metadata and settings.

# Basic usage
trix session create "My Project"

# With description and type
trix session create "Q4 Marketing Campaign" \
  --type project \
  --description "Social media and email campaigns for Q4"

# With tags for organization
trix session create "Bug Fix #1234" \
  --type task \
  --tags "bugfix,high-priority,backend"

# Link to a space
trix session create "Customer Research" \
  --space research \
  --type project

# Set retention policy
trix session create "Demo Session" \
  --type temporary \
  --retention temporary

# Auto-delete after 30 days
trix session create "Temp Project" \
  --retention auto_delete \
  --retention-days 30

# Create private session
trix session create "Personal Notes" --private

Flags

Flag	Type	Description
`--type`	string	Session type: `conversation`, `project`, `task`, `temporary` (default: conversation)
`--description`	string	Detailed description of the session
`--space`	string	Space ID or name to associate with this session
`--tags`	string	Comma-separated tags for organization
`--retention`	string	Retention policy: `permanent`, `temporary`, `auto_delete`, `on_completion`
`--retention-days`	integer	Days before auto-deletion (for auto_delete policy)
`--private`	boolean	Make session private (visible only to creator and admins)
`--origin-type`	string	Source of the session (e.g., "cli", "api", "zendesk")

Newly created sessions are automatically set as the current session, so subsequent memory operations will use it by default.

trix session list

List sessions with filtering, sorting, and pagination.

# List all sessions
trix session list

# Filter by status
trix session list --status active
trix session list --status paused
trix session list --status completed

# Filter by type
trix session list --type project
trix session list --type conversation

# Filter by space
trix session list --space research

# Filter by tags (comma-separated)
trix session list --tags "frontend,q4"

# Search by name or description
trix session list --search "customer support"

# Combine filters
trix session list --type project --status active --tags "frontend"

# Sort and order
trix session list --sort created_at --order desc
trix session list --sort last_active_at --order desc
trix session list --sort name --order asc

# Pagination
trix session list --limit 50 --offset 0

# Include archived sessions
trix session list --include-archived

# JSON output
trix session list -o json

Flags

Flag	Type	Description
`--status`	string	Filter by status: active, paused, completed, archived
`--type`	string	Filter by type: conversation, project, task, temporary
`--space`	string	Filter by space ID or name
`--tags`	string	Filter by tags (comma-separated, matches any)
`--search`	string	Search in name and description
`--sort`	string	Sort by: created_at, updated_at, last_active_at, name
`--order`	string	Sort order: asc, desc (default: desc)
`--limit`	integer	Maximum results to return (default: 20)
`--offset`	integer	Number of results to skip
`--include-archived`	boolean	Include archived sessions in results
`--format`	string	Output format: table, json (default: table)

trix session get

Get detailed information about a specific session.

# Get by session ID
trix session get sess_abc123

# Get current session
trix session get current

# JSON output with all details
trix session get sess_abc123 -o json

Displays complete session information including:

Session ID, name, description, and type
Status and lifecycle timestamps (created, updated, last active)
Memory and message counts
Associated space and tags
Retention policy and privacy settings

trix session switch

Switch to a different session, making it the current session for subsequent operations.

# Switch by session ID
trix session switch sess_abc123

# Switch by name (searches for match)
trix session switch "Customer Support"

# If multiple matches, you'll be prompted to select

The CLI remembers your current session in ~/.trix/current-session. Memory operations will automatically use this session unless you specify --session.

Name matching: If you provide a name instead of an ID, the CLI searches for sessions matching that name. If multiple matches are found, you'll see a list to choose from.

trix session current

Display the currently active session.

# Show current session
trix session current

# Output:
# Current session: sess_abc123
# Name: Customer Support Chat
# Type: conversation
# Status: active
# Memory count: 47

If no current session is set, the command will indicate this. Use trix session switch to set one.

trix session update

Update session metadata, tags, or settings.

# Update name
trix session update sess_abc123 --name "Updated Name"

# Update description
trix session update sess_abc123 \
  --description "New description here"

# Update tags
trix session update sess_abc123 --tags "updated,tags,list"

# Change retention policy
trix session update sess_abc123 \
  --retention auto_delete \
  --retention-days 30

# Toggle privacy
trix session update sess_abc123 --private true
trix session update sess_abc123 --private false

# Update current session
trix session update current --tags "in-progress"

Flags

Flag	Description
`--name`	Update session name
`--description`	Update description
`--tags`	Replace tags (comma-separated)
`--retention`	Update retention policy
`--retention-days`	Update retention days
`--private`	Update privacy setting (true/false)

trix session delete

Delete a session and all associated memories.

# Delete with confirmation prompt
trix session delete sess_abc123

# Skip confirmation
trix session delete sess_abc123 --yes

Deleting a session permanently removes the session and all memories created within it. This action cannot be undone. Consider completing or archiving instead.

trix session pause

Pause the current session, preventing new memories from being added.

# Pause current session
trix session pause

# Pause specific session
trix session pause sess_abc123

Paused sessions are read-only. Attempting to create memories in a paused session will fail. Resume the session to continue working.

trix session resume

Resume a paused session, allowing new memories to be added again.

# Resume a paused session
trix session resume sess_abc123

# Resume and switch to it
trix session resume sess_abc123
trix session switch sess_abc123

Only paused sessions can be resumed. Completed or archived sessions cannot be reopened.

trix session memories

List all memories linked to a session. This provides a quick way to see all memories that were created within a specific session context.

# List memories for current session
trix session memories

# List memories for a specific session
trix session memories sess_abc123

# Limit results
trix session memories --limit 20

# Paginate results
trix session memories --limit 50 --offset 100

# JSON output for scripting
trix session memories -o json

Flags

Flag	Type	Description
`--limit, -l`	integer	Maximum memories to return (default: 50)
`--offset, -o`	integer	Number of memories to skip for pagination (default: 0)
`--format, -f`	string	Output format: table, json (default: table)

This command shows all memories that have a session_id matching the specified session. It's useful for reviewing work done during a session or exporting session content.

trix session complete

Mark a session as completed with an optional summary.

# Complete current session
trix session complete

# Complete with summary
trix session complete --summary "Successfully implemented all features"

# Complete specific session
trix session complete sess_abc123 \
  --summary "Bug fixed and tested in production"

Completed sessions are read-only and can include a summary describing the outcome. This is useful for reviewing past work and maintaining a record of what was accomplished.

Flags

Flag	Description
`--summary`	Summary of the completed work (recommended)

Session-Aware Memory Commands

Memory commands support the --session flag to work within session context:

# Create memory in current session
trix mem create "Important note" --session current

# Create in specific session
trix mem create "Another note" --session sess_abc123

# List memories from current session
trix mem list --session current

# Search within a session
trix mem search "query" --session sess_abc123

# Combine with other filters
trix mem list --session current --tags "important" --limit 50

# Without --session flag, uses current session if set
trix session switch sess_abc123
trix mem create "Auto-uses current session"

If you've set a current session with trix session switch, memory commands automatically use it. The --session flag overrides this default.

Output Formats

Most session commands support both table (default) and JSON output:

# Table output (default, human-readable)
trix session list

# JSON output (for scripting)
trix session list -o json

# Pipe to jq for processing
trix session list -o json | jq '.data[] | select(.status == "active")'

# Get specific fields
trix session list -o json | jq '.data[] | {name, memory_count}'

Table Output Features

Color-coded status indicators (green=active, yellow=paused, blue=completed)
Relative timestamps ("2 hours ago", "3 days ago")
Current session marked with -> indicator
Truncated content for readability
Memory and message counts

Common Usage Examples

Daily Work Session

# Start your day
trix session create "Work - $(date +%Y-%m-%d)" --type project

# Work on tasks
trix mem create "Completed code review for PR #456"
trix mem create "Fixed bug in authentication flow"

# Take a break
trix session pause

# Resume after lunch
trix session resume current

# End of day
trix session complete --summary "Productive day: 2 PRs reviewed, 1 bug fixed"

Project Tracking

# Create project session
trix session create "Q1 Mobile App" \
  --type project \
  --tags "mobile,ios,android" \
  --space product

# Track progress over weeks
trix session switch "Q1 Mobile App"
trix mem create "Completed user authentication flow"
# ... more work ...

# Review project
trix mem list --session current
trix session get current

# Complete project
trix session complete --summary "App launched successfully with 10k downloads"

Customer Support

# New support ticket
trix session create "Support #7890 - Login issues" \
  --type conversation \
  --origin-type "zendesk"

# Log conversation
trix mem create "User: Can't login, getting 'Invalid credentials'"
trix mem create "Agent: Verified account exists, sent password reset"
trix mem create "User: Successfully logged in after reset"

# Close ticket
trix session complete --summary "Password reset resolved login issue"

Scripting with Sessions

Use JSON output and shell commands for automation:

#!/bin/bash

# Get all active project sessions
SESSIONS=$(trix session list \
  --type project \
  --status active \
  -o json | jq -r '.data[].id')

# Process each session
for sid in $SESSIONS; do
  echo "Processing session: $sid"
  MEMORIES=$(trix mem list --session $sid -o json)
  echo "  Memory count: $(echo $MEMORIES | jq '.pagination.total')"
done

# Find sessions inactive for > 7 days
trix session list -o json | \
  jq '.data[] | select(.last_active_at < (now - 7*86400)) | .name'

# Auto-complete old sessions
OLD_SESSIONS=$(trix session list \
  --status active \
  -o json | \
  jq -r '.data[] | select(.created_at < (now - 30*86400)) | .id')

for sid in $OLD_SESSIONS; do
  trix session complete $sid --summary "Auto-completed after 30 days"
done

Next Steps

Sessions Guide - Conceptual overview and best practices
Sessions API - REST API documentation
Memory Commands - Session-aware memory operations
Advanced CLI - Automation and scripting