> ## Documentation Index > Fetch the complete documentation index at: https://docs.cortex.foundation/llms.txt > Use this file to discover all available pages before exploring further. # CLI sessions > Every interactive run is a session written to disk: list, resume, rewind, fork, export, import, share, protect and clean up Every interactive run of the CLI is a **session**: the transcript, the tool calls, and the context Cortex built up along the way. Sessions are written to disk as the work happens, so closing the terminal does not lose anything and you can pick the work back up later. The CLI also remembers which coding session belongs to which workspace, so a terminal turn continues the same work you see in the web app. This page covers the commands that act on sessions from your shell, the in-session commands that act on the one you are in, rewinding and forking, export and import, sharing a link, protecting a session from cleanup, and where the files live. ## Six commands from the shell | Command | What it does | | ----------------------------- | ------------------------ | | `cortex sessions` | List sessions | | `cortex resume [SESSION_ID]` | Open one again | | `cortex export [SESSION_ID]` | Write one out as a file | | `cortex import ` | Read one back in | | `cortex delete ` | Delete one | | `cortex lock [SESSION_ID]` | Protect one from cleanup | Rewinding, forking and sharing are things you do **inside** a session, with `/rewind`, `/fork` and `/share`. There is no `cortex rewind`, `cortex fork` or `cortex share` command, and the `--share` flag on `cortex run` is declared but refused: it stops the run with `--share is not supported by the Code service contract. No turn was submitted.` ## List sessions ```bash theme={null} cortex sessions ``` By default this shows the sessions started in the current directory. | Flag | Effect | | ------------------------------ | --------------------------------------- | | `--all` | Include sessions from other directories | | `--days`, `--since`, `--until` | Filter by date | | `--favorites` | Only the ones you marked | | `-s`, `--search` | Match on title or id | | `-l`, `--limit` | Cap the number of rows | | `--json` | Machine-readable output | ## Resume ```bash theme={null} cortex resume # pick from recent sessions cortex resume --last # straight back into the most recent one cortex resume --pick # force the picker cortex resume # a specific session cortex resume --all # do not filter the picker by directory ``` `--no-session` is declared on the same command but cannot be combined with it: resuming with it set fails with `--no-session is incompatible with resume`. Treat it as a flag for the [command reference](/cli/reference) rather than a daily control. The picker lists recent sessions with what each one was about; typing filters the list, and the footer strip at the bottom of the screen names the keys that apply to it, including starting a new session instead. Inside a running session, `/resume` opens the same picker and `Ctrl+r` searches past sessions. Non-interactive runs can continue a session too: `cortex run --continue` picks up the most recent one and `cortex run --session ` continues a named one. A [goal](/cli/goal) comes back with the session it belongs to. ## Start fresh, or clear the conversation `/new` starts a new session without leaving the TUI. `/clear` empties the conversation but keeps the session you are in; it asks first and tells you what is dropped and what is kept, because your files and your configuration are untouched either way. `/session` prints the details of the session you are in, `/rename` gives it a name, and `/timeline` shows its timeline. `/favorite` and `/unfavorite` mark and unmark it, and `f` toggles the mark on the selected row in the sessions panel. ## Rewind, undo, fork Press `Esc` twice in quick succession to open the rewind overlay, which walks back through the session to an earlier point. The overlay has its own keys and lists them while it is open. From the composer: * `/rewind` optionally takes a number of steps. * `/undo` and `/redo` step the last action back and forward. * `/fork` starts a new session from this one, optionally with a name, leaving the original as it was. * `/ghost` manages ghost commits for undo. Forking is the safe way to try a second approach: the fork carries the conversation so far, and anything you do in it stays out of the original. ## Export ```bash theme={null} cortex export # the most recent session cortex export -o out.json # choose the output path cortex export -f yaml # json, yaml or csv cortex export --pretty # readable formatting ``` From inside a session, `/export` offers Markdown, JSON or plain text and writes a file named in the pattern `cortex__<date>.<ext>`. ## Import ```bash theme={null} cortex import session.json cortex import https://cortex.foundation/a-session.json cortex import - # read from standard input cortex import session.json --force # overwrite an existing session cortex import session.json --resume # import it and open it ``` Import is how a session moves between machines, and with `-` it composes with anything that can write JSON to a pipe. ## Share a link `/share` creates a link to the session. It takes a duration, and the values it accepts are `30d`, `24h`, `60m` and `never`. Sharing is an in-session action only: `cortex run --share` is refused before the run starts. ## Protect a session from cleanup ```bash theme={null} cortex lock add <SESSION_ID> -r "reference for the migration" cortex lock list cortex lock check <SESSION_ID> cortex lock remove <SESSION_ID> ``` `cortex lock` is also available as `cortex protect`. A locked session survives the cleanup commands below, which makes it the right thing to do to the session you will want to point at in three months. The reason you give with `-r` is there so the lock explains itself later. ## Delete and clean up ```bash theme={null} cortex delete <SESSION_ID> # asks first cortex delete <SESSION_ID> --yes # do not ask ``` `-y/--yes` skips the confirmation, and `-f/--force` is accepted as well. Housekeeping across everything the CLI has written is a separate command, `cortex compact`, also available as `cortex gc` and `cortex cleanup`: ```bash theme={null} cortex compact status # what cleanup would reclaim cortex compact run # compact logs, sessions and history ``` It also takes `logs`, `vacuum` and `config` subcommands. ## Where sessions live Sessions are files under the Cortex home directory, one directory per session at `~/.cortex/sessions/{session-id}/`. A session with a goal keeps it alongside as its own file, which is why a goal survives resuming and compaction. `~/.cortex/code-sessions.json` is the map from a workspace to the coding session it belongs to. Two configuration keys govern the history file: ```toml theme={null} [history] persistence = "save-all" # or "none" to keep no history max_bytes = 10000000 ``` Setting `persistence` to `none` is the way to run without a stored history at all. See [Data locations](/cli/data-locations) for everything the CLI writes and [Configuration](/cli/configuration) for where to set these. ## Related * [Goals](/cli/goal) - the objective that rides along with a session * [The TUI](/cli/tui) - the sessions panel, the resume picker and the rewind overlay * [Headless and one-shot runs](/cli/headless) - continuing a session from a script * [Data locations](/cli/data-locations) - what is on disk, and what `cortex compact` reclaims * [Code sessions](/code/sessions) - the same work in the web app