btraceio · jbachorik · Jan 9, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -222,7 +222,8 @@ The jfr-shell module provides a powerful interactive environment for JFR analysi
 - **Session-based**: Open JFR files and maintain analysis state
 - **JfrPath Query Language**: Concise path-based queries with filtering, aggregation, and transformations
 - **Event Decoration**: Join/correlate events by time overlap or correlation keys
-- **Built-in Commands**: `show`, `metadata`, `chunks`, `cp`, `open`, `sessions`, `info`, `help`
+- **Session Export/Import**: Save and share complete analysis sessions (variables, queries, settings)
+- **Built-in Commands**: `show`, `metadata`, `chunks`, `cp`, `open`, `sessions`, `info`, `export`, `import`, `help`
 - **Multiple Output Formats**: Table (default) and JSON
 - **Example Scripts**: Pre-built analysis examples in `jfr-shell/src/main/resources/examples/`
 
@@ -233,6 +234,14 @@ The jfr-shell module provides a powerful interactive environment for JFR analysi
 - Memory-efficient lazy evaluation
 - Examples: monitor contention analysis, request tracing, GC impact assessment
 
+**New Feature: Session Export/Import**
+- Export complete session state to JSON (variables, queries, settings, recording info)
+- Import previously exported sessions to restore analysis state
+- Options: `--include-results` to cache query results, `--max-rows` to limit result size
+- Path remapping for sharing across machines: `--remap-path` on import
+- Use cases: save progress, share analysis templates, document incidents
+- Example: `export --include-results analysis.json` then `import --alias restored analysis.json`
+
 #### JFR Shell Usage:
 ```bash
 # Start interactive shell

diff --git a/doc/jfr-shell-tutorial.md b/doc/jfr-shell-tutorial.md
@@ -12,7 +12,7 @@ This tutorial teaches you how to use JFR Shell, an interactive CLI for exploring
 7. [Aggregations and Statistics](#aggregations-and-statistics)
 8. [Advanced Queries](#advanced-queries)
 9. [Event Decoration and Joining](#event-decoration-and-joining)
-10. [Multi-Session Management](#multi-session-management)
+10. [Multi-Session Management and Session Export/Import](#multi-session-management-and-session-exportimport)
 11. [Non-Interactive Mode](#non-interactive-mode)
 12. [Real-World Examples](#real-world-examples)
 
@@ -825,7 +825,9 @@ Event decoration enables powerful cross-event analysis:
 
 See the [JfrPath Reference](jfrpath.md) for complete syntax details and [examples/](../jfr-shell/src/main/resources/examples/) for more use cases.
 
-## Multi-Session Management
+## Multi-Session Management and Session Export/Import
+
+### Multi-Session Management
 
 Work with multiple recordings simultaneously:
 
@@ -862,6 +864,141 @@ jfr> close prod
 jfr> close --all
 ```
 
+### Session Export/Import
+
+Save your analysis progress and share sessions with teammates.
+
+#### Export Session State
+
+Export includes recording info, all variables, and settings:
+
+```bash
+# Do some analysis
+jfr> open recording.jfr --alias analysis
+jfr> set threshold = 1000
+jfr> set bigReads = events/jdk.FileRead[bytes>${threshold}]
+jfr> show ${bigReads} | top(10, by=bytes)
++-----------------------------+--------+
+| path                        | bytes  |
++-----------------------------+--------+
+| /data/large-file.bin        | 524288 |
+| /logs/app.log               | 102400 |
+...
+
+# Export session (queries only)
+jfr> export my-analysis.json
+Exporting session...
+Session exported to: /path/to/my-analysis.json
+  Variables: 2 session, 0 global
+
+# Export with cached results (larger file)
+jfr> export --include-results analysis-full.json
+Exporting session...
+Session exported to: /path/to/analysis-full.json
+  Variables: 2 session, 0 global
+  Included cached query results (--include-results)
+```
+
+#### Import Session State
+
+Restore a previously exported session:
+
+```bash
+# Close current session
+jfr> close --all
+
+# Import saved session
+jfr> import my-analysis.json
+Importing session from /path/to/my-analysis.json...
+Snapshot version: 1.0, exported: 2025-01-10T15:30:00Z
+Session imported successfully.
+  Session ID: 1
+  Alias: imported
+  Recording: /path/to/recording.jfr
+  Variables: 2 session, 0 global
+
+# Variables are restored
+jfr> vars
+Session variables:
+  threshold = 1000
+  bigReads = lazy[events/jdk.FileRead[bytes>${threshold}]] (not evaluated)
+
+# Continue analysis
+jfr> show ${bigReads} | select(path, bytes) | top(5)
+```
+
+#### Import with Path Remapping
+
+Share sessions across machines with different file paths:
+
+```bash
+# On teammate's machine with different path
+jfr> import --remap-path /their/path/recording.jfr my-analysis.json
+Using remapped path: /their/path/recording.jfr
+Session imported successfully.
+  Session ID: 1
+  Alias: imported
+  Variables: 2 session, 0 global
+
+# All variables work with remapped recording
+jfr> show ${bigReads}
+```
+
+#### Use Cases
+
+**1. Save Analysis Progress**
+
+```bash
+# At end of work day
+jfr> export daily-analysis.json
+
+# Next day
+jfr> import daily-analysis.json
+jfr> # Continue where you left off
+```
+
+**2. Share Analysis with Team**
+
+```bash
+# Senior developer creates analysis template
+jfr> set threshold = 1048576
+jfr> set topN = 10
+jfr> set cpuThreshold = 0.8
+jfr> export team-template.json
+
+# Team members use template
+jfr> import team-template.json
+jfr> open their-recording.jfr
+jfr> # Template variables ready to use
+jfr> show events/jdk.FileRead[bytes>${threshold}] | top(${topN}, by=bytes)
+```
+
+**3. Document Incident Analysis**
+
+```bash
+# During incident investigation
+jfr> open incident-recording.jfr --alias incident
+jfr> set errorThreshold = 100
+jfr> set criticalMethods = events/jdk.ExecutionSample[...] | groupBy(method)
+jfr> show ${criticalMethods}
+
+# Save for postmortem
+jfr> export --include-results incident-analysis.json
+
+# Later, team reviews exact same analysis
+jfr> import incident-analysis.json
+jfr> # All queries and results preserved
+```
+
+**Export Options:**
+- `--include-results`: Include cached query results
+- `--max-rows N`: Limit rows per variable (default: 1000)
+- `--format json`: Output format (JSON only in Phase 1)
+
+**Import Options:**
+- `--alias NAME`: Custom alias for imported session
+- `--remap-path PATH`: Override recording file path
+
 ## Non-Interactive Mode
 
 Execute queries without entering the shell - perfect for scripts and CI:

diff --git a/doc/jfr_shell_usage.md b/doc/jfr_shell_usage.md
@@ -50,6 +50,8 @@ jfr> show events/jdk.FileRead/bytes --limit 5
 - `use <id|alias>`: Switch current session.
 - `close [<id|alias>|--all]`: Close a session or all.
 - `info [<id|alias>]`: Show session information.
+- `export [--include-results] [--max-rows N] [--format json] <path>`: Export session state to file.
+- `import [--alias NAME] [--remap-path PATH] <session-file>`: Import session state from file.
 
 ### Querying and Browsing
 - `show <expr> [--limit N] [--format table|json] [--tree] [--depth N] [--list-match any|all|none]`: Evaluate a JfrPath expression. For list fields, `--list-match` sets default matching mode.