Syntax
vectra-guard session <subcommand> [options]
vg session <subcommand> [options]
Subcommands
session start
Start a new tracked session.
vg session start --agent <name> [--workspace <path>]
Name of the agent or user starting the session (e.g., “cursor-ai”, “manual”, “github-actions”)
Workspace directory path. Defaults to current working directory.
session end
End an active session.
vg session end <session-id>
session-id: ID of the session to end
session list
List all sessions for the current workspace.
Output: Table with session ID, agent, start time, duration, commands, violations, and risk score.
session show
Show detailed information about a specific session.
vg session show <session-id>
session-id: ID of the session to display
Output: Full session details including all commands, file operations, timestamps, exit codes, and findings.
session record
Manually record a command in a session (used by shell trackers).
vg session record --command <cmd> --exit-code <code> [--session <id>]
Command string to record in the session
Exit code of the executed command
Session ID. If not provided, uses the current workspace session.
Examples
Start a session and export ID
SESSION=$(vg session start --agent "cursor-ai")
export VECTRAGUARD_SESSION_ID=$SESSION
echo "Session started: $SESSION"
Execute commands in a session
vg exec -- npm install
vg exec -- npm test
vg exec -- git commit -m "feat: add feature"
# All automatically tracked in $SESSION
View session summary
vg session show $SESSION
# Output:
# Session: session-abc123
# Agent: cursor-ai
# Workspace: /home/user/project
# Start Time: 2026-03-03T10:00:00Z
# Status: Active
# Risk Score: 12
# Violations: 0
#
# Commands (3):
# 1. [10:00:05] npm install (exit: 0, risk: low)
# 2. [10:01:15] npm test (exit: 0, risk: low)
# 3. [10:02:30] git commit -m "feat: add feature" (exit: 0, risk: low)
List all sessions
vg session list
# SESSION ID AGENT START TIME DURATION COMMANDS VIOLATIONS RISK
# session-abc123 cursor-ai 2026-03-03 10:00:00 5m 30s 3 0 12
# session-def456 manual 2026-03-03 09:00:00 1h 15m 8 1 24
End a session
vg session end $SESSION
# Session ended: session-abc123
# Commands: 3, Violations: 0, Risk Score: 12
JSON output for automation
vg --output json session show $SESSION | jq '.commands[] | select(.exit_code != 0)'
# Find all failed commands in a session
Session Storage
Sessions are stored in .vectra-guard/sessions/ within the workspace directory. Each session is a JSON file containing:
- Session metadata (ID, agent, workspace, timestamps)
- All executed commands with timestamps, exit codes, risk levels
- File operations performed
- Security findings and violations
- Risk scores and metadata
- exec - Execute commands (auto-tracks in sessions)
- audit - Audit session activity