isesh

isesh is the session CLI: it creates sessions with a profile and workspace, controls their lifecycle (attach, stop, kill, delete, archive, rename), and manages prompts and profiles. Session state is managed with istate.

Starting Sessions

start

Start a session with profile and workspace options.

isesh start <name> [options]

Options:

• -p, --profile <name> - Profile to use (mwd, tda-manager, tda-worker, etc.)
• -w, --workspace <path> - Working directory for the session
• -d, --detach - Start in background
• --cli <type> - CLI type: claude, cursor, codex
• --env-var <KEY=VAL> - Set an environment variable for this session only (repeatable)

Examples:

# Start with MWD profile
isesh start my-task -p mwd

# Start with profile and workspace
isesh start my-project -p mwd -w ~/projects/my-app

# Start Manager session
isesh start project-mgr -p tda-manager -w ~/projects/my-app

# Start Worker session
isesh start worker1 -p tda-worker -w ~/projects/my-app

# Start with different CLI
isesh start my-task -p mwd --cli cursor

팁

tda-manager and tda-worker sessions can also be created and managed as a team with itda (e.g. itda list, itda tree, itda stop).

list

List sessions. Only running sessions are shown by default.

isesh list [options]

Options:

• -a, --all - Show all sessions (stopped and archived too)
• -p, --profile <name> - Filter by profile
• --json, -j - Output as JSON

show

Show session configuration.

isesh show <name>

Profile Management

profile list

List available profiles.

isesh profile list

profile show

Show profile details.

isesh profile show <name>

Example:

isesh profile show mwd
isesh profile show tda-manager

profile create

Create a new profile.

isesh profile create <name> [options]

Options:

• --system-prompt, -s <prompt> - System prompt

Prompt Management

prompt list

List available prompts.

isesh prompt list

prompt show

Display a prompt's content.

isesh prompt show <name>

Example:

isesh prompt show worker-management

prompt add

Add a new prompt (pipe content via stdin).

echo "Your prompt content" | isesh prompt add <name>

prompt delete

Delete a prompt.

isesh prompt delete <name>

State Management

Session state persists data across restarts. It is managed with the separate istate CLI (installed with IST). isesh no longer has a state subcommand.

istate works on three scopes, chosen with --scope:

• session (default) — your own session's state. The current session comes from the environment; pick another with -s, --session <name>.
• namespace (alias: profile) — shared by a namespace, given with --namespace <name> (or -p, --profile <name>).
• global — shared by every session.

istate list

List state keys (all scopes by default).

istate list [options]

Options:

• --scope <scope> - Show only one scope: session, namespace (alias profile), global
• -v, --verbose - Show values and a metadata summary (author, age, expiry)
• --stale - Show only expired keys

istate get

Get a state value.

istate get <key> [options]

By default it prints the value, or (undefined) when the key is absent, and exits 0 either way. With --strict it exits 0 when found, 2 when not found, and 1 on a read error. --json prints a one-line JSON result (and implies --strict).

Example:

istate get current-task
istate get current-task --strict

istate set

Set a state value (your own session's state by default).

istate set <key> <value> [options]

Options:

• --scope <scope> - session (default), namespace (alias profile), global
• --ttl <dur> - Expire after a duration, e.g. 7d, 12h, 30m, 1d12h
• --durable - Mark as a durable shared value: never expires, never garbage-collected
• --allow-global --reason <text> - Required to write to the global scope

Example:

istate set current-task "Implement user authentication"
istate set current-task "Implement user authentication" --ttl 12h

istate delete

Delete a state value.

istate delete <key> [options]

istate gc

Garbage-collect state (archive first, then delete past retention).

• Stage 1: expired non-durable keys are moved to ~/.ist/state/archive/<scope>/ (kept, not deleted).
• Stage 2: archived entries older than 30 days are hard-deleted (--purge deletes them now).
• Durable keys are never touched. By default all scopes are scanned.

istate gc [options]

Options:

• --scope <scope> - Restrict to one scope: session, namespace (alias profile), global (default: all)
• --session, -s <name> - Session ID (with --scope session)
• --namespace <name> / --profile, -p <name> - Namespace ID (with --scope namespace)
• --mine - Only collect entries authored by the current session
• --dry-run - Report the plan only; change nothing
• --purge - Hard-delete archived entries immediately (skip the 30-day retention)
• --migrate - Print a migration plan for legacy keys only (never mutates)

Example:

istate gc --dry-run             # Preview what would be archived/deleted
istate gc --mine                # Only collect keys authored by this session
istate gc --scope global        # Restrict to the global scope
istate gc --migrate --dry-run   # Print a migration plan only (no changes)

istate drop / rename / path

istate drop --session <name> [--dry-run]                # Archive and remove a whole session's state
istate rename --session <old-name> <new-name>           # Move a session's state to a new name
istate path                                             # Show the state file path

isesh rename and isesh delete don't touch state: use istate rename / istate drop for that.

Authentication

auth login

Log in with the IST auth CLI.

isesh auth login

auth logout

Log out with the IST auth CLI.

isesh auth logout

auth whoami

Show the current authenticated user.

isesh auth whoami [options]

Options:

• --json - Output in JSON format

auth status

Check authentication status.

isesh auth status

Session Control

isesh owns the session lifecycle. Use these commands (not ilogsession) to control sessions.

attach / stop / kill

isesh attach <name>   # Attach to a running session (detach with Ctrl-b d)
isesh stop <name>     # Stop session
isesh kill <name>     # Kill session

Implementation detail: these three are passed through to the loggable session layer (@ist/loggable-core, the library ilogsession is built on).

delete

Delete a session. By default this removes its config and prompts so the name can be re-created cleanly; logs are kept unless you pass --all. Running sessions are refused, so stop them first. State is not removed; use istate drop --session <name> for that.

isesh delete [name] [options]

Options:

• --all - Also delete the session's logs
• --config-only - Delete only the config (keep prompts and logs)
• --pattern <glob> - Delete every session matching a glob pattern
• --dry-run - Show what would be deleted without deleting

Examples:

isesh delete my-session                    # config + prompts
isesh delete my-session --all              # also remove logs
isesh delete --pattern 'test-*' --dry-run  # preview a bulk delete

노트

ilogsession delete <name> is a different, lower-level command: it stops the session and removes its logs only. See ilogsession.

archive

Archive a session.

isesh archive <name>

rename

Rename a session. These session artifacts are renamed: session config (~/.ist/sesh/configs/{name}.json), session prompts (~/.ist/prompts/sessions/{name}/), session logs (~/.ist/logs/{name}/), the active session file (~/.ist/sessions/{name}.json), the logs metadata (name field), and the terminal session (ist--{name}). Session state is not moved: run istate rename --session <old-name> <new-name> as well.

isesh rename <old-name> <new-name>

Example:

isesh rename old-session new-session

Configuration

Profiles are stored in ~/.ist/profiles/.

State is stored in ~/.ist/state/ and managed with istate.

Prompts are stored in scope subdirectories of ~/.ist/prompts/: global/ (all sessions), profiles/<profile>/ (sessions using that profile), and sessions/<session>/ (one session). See skit.