Tags

Organize your shell sessions by project, environment, or purpose — then filter search, stats, and replay by tag for focused insights.

Quick Start

Create a tag, then associate it with your current session. All commands in the session inherit the tag.

suv tag create deploy -d "Production deployments"
suv tag associate deploy

Commands

Create a tag

Create a new named tag with an optional description. Tag names are case-insensitive and must be unique.

suv tag create <NAME> [-d <DESCRIPTION>]

Flag	Description
`-d <DESCRIPTION>`	Optional human-readable description for the tag.

List tags

Display all existing tags with their descriptions and associated session counts.

suv tag list

Associate a tag with a session

Link a tag to a session. If no session ID is provided, the tag is associated with your current active session.

suv tag associate <TAG_NAME> [--session-id <ID>]

Flag	Description
`--session-id <ID>`	Associate the tag with a specific session instead of the current one. Useful for retroactively tagging past sessions.

Update a tag

Rename a tag or change its description. All existing session associations are preserved.

suv tag update <NAME> [--new-name <NAME>] [-d <DESCRIPTION>]

Flag	Description
`--new-name <NAME>`	Rename the tag. All session associations update automatically.
`-d <DESCRIPTION>`	Update the tag description.

Tags in the Search TUI

Tags integrate directly into the interactive search interface (suv search):

Ctrl+T — associate the current active session with a tag. A picker appears listing all available tags.
Tagged sessions display the tag name in the detail preview pane (toggle with Tab).

Auto-tagging

Instead of manually tagging every session, configure directory-to-tag mappings in suv settings (Auto-tags section). When you start a session inside a mapped directory (or any subdirectory), the tag is applied automatically.

Example mappings:

~/work → Work — any session started under your work directory gets the "Work" tag.
~/projects/api → API — sessions in the API project are tagged "API".
~/infra → Infrastructure — infrastructure work is tracked separately.

Auto-tagging is the recommended approach for most users. It requires no ongoing effort and gives you per-project analytics out of the box.

Filtering by Tag

Once sessions are tagged, use the --tag flag across multiple Suvadu commands to scope results to a specific tag.

Search by tag

Filter search results to only show commands from sessions with a given tag.

suv search --tag work

Stats by tag

View usage statistics scoped to a tag — see top commands, success rates, and busiest hours for just that project or environment.

suv stats --tag work

Replay by tag

Replay command timelines from sessions associated with a tag.

suv replay --tag work

Examples

Create a tag with a description

suv tag create deploy -d "Production deployments"

Tag the current session

suv tag associate deploy

Tag a past session

suv tag associate deploy --session-id abc123

Rename a tag

suv tag update deploy --new-name production

Update a tag description

suv tag update production -d "All production deployment sessions"

List all tags

suv tag list

Search within tagged sessions

suv search --tag production

How It Works

Tags are stored in your local SQLite history database. Each tag is a named record; sessions are linked to tags via a many-to-many association table, meaning a session can have multiple tags and a tag can span many sessions. All tag operations are instant local writes. Tags are included in suv export output and can be restored via suv import.

Tip: Combine auto-tagging with suv stats --tag to get automatic per-project analytics. Set up your directory mappings once in settings and never think about tagging again.