> ## Documentation Index
> Fetch the complete documentation index at: https://www.landbase.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# How to use sessions to continue research across runs

> Use the --session flag to pick up a search conversation where you left off, refine results across multiple commands, and review run history.

# How to use sessions to continue research across runs

This guide shows you how to use the `--session` flag to maintain a running research conversation across multiple CLI commands — refining results step by step without starting over.

***

## What sessions do

Every search creates a session on the Landbase backend. By default each command creates a fresh session. When you pass `--session=<label>`, the CLI:

1. Looks up the label in `~/.landbase/sessions.json` to find the session UUID
2. Sends that UUID with the request so Landbase treats your prompt as a continuation of the prior conversation
3. Saves the label → UUID mapping after the first run so future commands reuse it automatically

This means "narrow to 50-200 employees" in session `uk-saas` is understood in the context of the earlier "find SaaS companies in London" search — you do not need to repeat the original criteria.

***

## Basic usage

Start a session with any search:

```bash theme={null}
landbase-cli "find SaaS companies in London" --session=uk-saas
```

Then refine it:

```bash theme={null}
landbase-cli "narrow to 50-200 employees" --session=uk-saas
landbase-cli "only ones with a LinkedIn company page" --session=uk-saas --download=uk-saas-final.jsonl
```

Each command continues from where the last one left off.

***

## Choosing a session label

Labels can be any short string. Use something meaningful to the research task:

```bash theme={null}
--session=fintech-nyc
--session=acme-account-research
--session=q3-outbound
```

Labels are stored locally and are just aliases for session UUIDs. They are never sent to the Landbase API — only the UUID is.

***

## Review what happened in a session

List all runs for a session:

```bash theme={null}
landbase-cli runs list --session=uk-saas
```

Fetch the details of a specific run:

```bash theme={null}
landbase-cli runs get <run-id> --session=uk-saas
```

The `runs` commands show you what queries were sent, what datasets were created, and the timestamps for each run in the session.

***

## Start a new session on the same topic

If you want a clean slate for a similar research task, just use a new label:

```bash theme={null}
landbase-cli "find SaaS companies in London" --session=uk-saas-v2
```

The old `uk-saas` session is unaffected.

***

## How sessions work in Claude Code

When you run landbase-cli commands through Claude Code, the `CLAUDE_CODE_SESSION_ID` environment variable is automatically detected. The CLI records this alongside your session label for telemetry, and session continuity works the same way — use the same `--session` label in Claude's tool calls to maintain context.

***

## Find the session UUID for a label

If you need the raw UUID (for example to pass it to another tool), look it up in:

```bash theme={null}
cat ~/.landbase/sessions.json
```

Or from a search response — the `session_id` field in the JSON output is the UUID.

***

## Related

* [How sessions work](/docs/explanation/how-sessions-work) — deeper background on the label → UUID model and session lifetime
* [runs reference](/docs/reference/runs) — full reference for the `runs` command