The Archive · CLI reference · Commands

talos session

Lists, finds, labels, resumes, forks, shares, exports, imports and deletes sessions.

Reference for TALOS CLI 0.3.3 generated from the npm package · released Sep 30, 2026

TALOS CLI 0.5.2 is out; this page still describes 0.3.3 and updates with the next build.

Every conversation is a session, saved on your machine. <id> is the session id talos session list shows.

Operation	What it does
`list`default	Lists the sessions with their name, project, model, tags and pin.
`search`	Lists the sessions whose id, name, project or tags contain the text (case-insensitive).
`show`	Prints the details of a session, with its number of events.
`context`	Prints how full the context window of a session is, and when it will be compacted.
`rename`	Names a session; without a name, clears it.
`tag`	Adds a tag to a session.
`untag`	Removes a tag from a session.
`pin`	Pins a session to the top of the list.
`unpin`	Unpins a session.
`resume`	Continues a session, optionally with a new prompt; prints the id of the running session.
`fork`	Starts a new session from a copy of an existing one; prints the new id.
`share`	Writes a redacted copy of a session, safe to share: keys and secrets found in your environment are removed.
`export`	Writes a session to a file, for your own records.
`import`	Imports a session file exported by TALOS CLI or TALOS Desktop, as a read-only archive.
`delete`	Deletes a session and the command outputs kept for it.

Without an operation, talos session runs list.

`list`

Lists the sessions with their name, project, model, tags and pin.

talos session list

`search`

Lists the sessions whose id, name, project or tags contain the text (case-insensitive).

talos session search <text…>

Arguments

text: Words to find.

Exit codes and errors1

Code	Exit	Meaning
`SESSION_SEARCH_QUERY_REQUIRED`	`15`	The session could not be used. Pick a session from the list.

`show`

Prints the details of a session, with its number of events.

talos session show <id>

Arguments

id: The id talos session list shows.

Exit codes and errors1

Code	Exit	Meaning
`SESSION_NOT_FOUND`	`15`	That session was not found. Pick a session from the list.

`context`

Prints how full the context window of a session is, and when it will be compacted.

talos session context <id>

Arguments

id: The id talos session list shows.

Exit codes and errors1

Code	Exit	Meaning
`SESSION_CONTEXT_UNAVAILABLE`	`15`	The session could not be used. Pick a session from the list.

`rename`

Names a session; without a name, clears it.

talos session rename <id> [name…]

Arguments

id: Session id.
nameoptional: The new name.

`tag`

Adds a tag to a session.

talos session tag <id> <tag…>

Arguments

id: Session id.
tag: The tag (may contain spaces).

Exit codes and errors1

Code	Exit	Meaning
`SESSION_TAG_REQUIRED`	`15`	The session could not be used. Pick a session from the list.

`untag`

Removes a tag from a session.

talos session untag <id> <tag…>

Arguments

id: Session id.
tag: The tag to remove.

Exit codes and errors1

Code	Exit	Meaning
`SESSION_TAG_REQUIRED`	`15`	The session could not be used. Pick a session from the list.

`pin`

Pins a session to the top of the list.

talos session pin <id>

Arguments

id: The id talos session list shows.

Exit codes and errors1

Code	Exit	Meaning
`SESSION_TAG_REQUIRED`	`15`	The session could not be used. Pick a session from the list.

`unpin`

Unpins a session.

talos session unpin <id>

Arguments

id: The id talos session list shows.

Exit codes and errors1

Code	Exit	Meaning
`SESSION_TAG_REQUIRED`	`15`	The session could not be used. Pick a session from the list.

`resume`

Continues a session, optionally with a new prompt; prints the id of the running session.

talos session resume <id> [prompt…]

Arguments

id: Session id.
promptoptional: A new message for the session.

With a prompt, it runs on the session's model and says where its key comes from.

`fork`

Starts a new session from a copy of an existing one; prints the new id.

talos session fork <id>

Arguments

id: The id talos session list shows.

`share`

Writes a redacted copy of a session, safe to share: keys and secrets found in your environment are removed.

talos session share <id> --out <file>

Arguments

id: The id talos session list shows.

Options

--out <value>: The file to write (required).

Exit codes and errors2

Code	Exit	Meaning
`SESSION_SHARE_OUT_REQUIRED`	`15`	The session could not be used. Pick a session from the list.
`SESSION_NOT_FOUND`	`15`	That session was not found. Pick a session from the list.

`export`

Writes a session to a file, for your own records.

talos session export <id> --out <file> [--format json|jsonl|md]

Arguments

id: The id talos session list shows.

Options

--format <value> default json: json (whole session, default), jsonl (one event per line) or md (readable Markdown, secrets removed). Valuesjsonjsonlmd
--out <value>: The file to write (required).

The file is created readable only by you.

Exit codes and errors2

Code	Exit	Meaning
`SESSION_EXPORT_OUT_REQUIRED`	`15`	The session could not be used. Pick a session from the list.
`SESSION_NOT_FOUND`	`15`	That session was not found. Pick a session from the list.

`import`

Imports a session file exported by TALOS CLI or TALOS Desktop, as a read-only archive.

talos session import <file>

Arguments

file: A .json export, at most 256 MB.

Pending approvals in the file are dropped. The imported session cannot be run.

Exit codes and errors5

Code	Exit	Meaning
`SESSION_ID_REQUIRED`	`15`	The session could not be used. Pick a session from the list.
`SESSION_IMPORT_FILE_REQUIRED`	`15`	The session could not be used. Pick a session from the list.
`SESSION_IMPORT_INVALID`	`15`	The session could not be used. Pick a session from the list.
`SESSION_SCHEMA_UNSUPPORTED`	`15`	The session could not be used. Pick a session from the list.
`SESSION_IMPORT_ID_INVALID`	`15`	The session could not be used. Pick a session from the list.

`delete`

Deletes a session and the command outputs kept for it.

talos session delete <id>

Arguments

id: The id talos session list shows.