feat(cli): add /teleport command for portable session management

docs/cli/teleportation.md

@@ -0,0 +1,136 @@
+# Teleportation
+
+Teleportation lets you move your active AI engineering sessions between
+different machines. Unlike sharing a chat transcript, teleporting captures your
+entire workspace state, including your plans, tasks, tracker data, and full
+activity logs.
+
+By using teleportation, you can start a complex engineering task on your local
+laptop and "needlecast" it to a powerful remote server or a different
+development environment without losing your progress or context.
+
+## How it works
+
+Teleportation bundles all session-related data from your local Gemini temporary
+directory (`~/.gemini/tmp`) into a portable, compressed archive (`.tar.gz`). You
+can then transfer this archive to another machine and import it to resume
+working exactly where you left off.
+
+The bundle includes:
+
+- Chat history and conversation state.
+- AI-generated plans and task statuses.
+- Detailed activity logs and tool outputs.
+- Project-specific tracker data.
+
+## Export a session
+
+To package your current session for transfer, use the `/teleport export`
+command.
+
+1.  Run the export command in your active session:
+
+    ```bash
+    /teleport export
+    ```
+
+    This creates a file named `gemini-session-<short-id>.tar.gz` in your current
+    directory.
+
+2.  Optional: Specify a custom output path:
+
+    ```bash
+    /teleport export current my-backup.tar.gz
+    ```
+
+3.  Optional: Export a specific session by its ID:
+    ```bash
+    /teleport export session-abc-123
+    ```
+
+## Import a session
+
+To restore a session on a new machine, use the `/teleport import` command.
+
+1.  Move the exported tarball to the new machine.
+2.  Run the import command:
+    ```bash
+    /teleport import ./my-backup.tar.gz
+    ```
+3.  Resume the imported session:
+    ```bash
+    /resume <session-id>
+    ```
+    The import command will display the session ID you need to resume.
+
+## Security and privacy
+
+Teleportation includes several features to ensure your session data remains
+secure during transit.
+
+### Encryption
+
+You can encrypt your session bundle using AES-256-GCM. This ensures that even if
+the archive is intercepted, the contents cannot be read without your secret.
+
+To use encryption:
+
+1.  Add the `--secret` flag to your export command:
+    ```bash
+    /teleport export --secret
+    ```
+2.  Enter a password when prompted. Gemini CLI uses the Scrypt key derivation
+    function to protect your password against brute-force attacks.
+3.  When importing, add the `--secret` flag again:
+    ```bash
+    /teleport import ./encrypted-session.tar.gz --secret
+    ```
+
+You can also use the `GEMINI_TELEPORT_SECRET` environment variable or a key file
+with `--key-file <path>` to provide the secret without an interactive prompt.
+
+### Path traversal protection
+
+During the import process, Gemini CLI automatically scans the archive for
+malicious paths. It prevents any files from being extracted outside of the
+designated Gemini temporary directory, protecting your system from path
+traversal attacks.
+
+## Cloud blob storage
+
+Teleportation supports direct transfers to and from Google Cloud Storage (GCS)
+and Amazon S3. This lets you store your sessions in a centralized location that
+you control, without committing large log files to your Git repository.
+
+### Prerequisites
+
+To use cloud storage, you must have the corresponding cloud CLI installed and
+authenticated on your machine:
+
+- **GCS**: Requires `gcloud` or `gsutil`.
+- **S3**: Requires `aws`.
+
+### Cloud usage examples
+
+**Export directly to a bucket:**
+
+```bash
+/teleport export --blob gs://my-sessions-bucket/task-alpha.tar.gz
+```
+
+**Import directly from a bucket:**
+
+```bash
+/teleport import gs://my-sessions-bucket/task-alpha.tar.gz
+```
+
+**Secure cloud transfer:**
+
+```bash
+/teleport export --secret --blob s3://my-bucket/secure-session.tar.gz
+```
+
+## Next steps
+
+- Learn more about [Session management](./session-management.md).
+- Explore [Checkpointing](./checkpointing.md) for local file safety.

docs/reference/commands.md

@@ -442,6 +442,18 @@ Slash commands provide meta-level control over the CLI itself.
   - **`tools`**:
     - **Description:** Show tool-specific usage statistics.
 
+### `/teleport`
+
+- **Description:** Export or import sessions to make them portable across
+  machines.
+- **Sub-commands:**
+  - **`export [session-id] [output-path] [--secret] [--key-file <path>] [--blob <uri>]`**:
+    - **Description:** Packages the session state into a compressed archive.
+    - **Note:** Use `--secret` for AES-256 encryption or `--blob` to upload
+      directly to GCS/S3.
+  - **`import <path-or-uri> [--secret] [--key-file <path>]`**:
+    - **Description:** Restores a session from a local file or cloud URI.
+
 ### `/terminal-setup`
 
 - **Description:** Configure terminal keybindings for multiline input (VS Code,

docs/sidebar.json

@@ -43,6 +43,10 @@
             "label": "Manage sessions and history",
             "slug": "docs/cli/tutorials/session-management"
           },
+          {
+            "label": "Teleport sessions between machines",
+            "slug": "docs/cli/teleportation"
+          },
           {
             "label": "Plan tasks with todos",
             "slug": "docs/cli/tutorials/task-planning"
@@ -136,6 +140,7 @@
           { "label": "Sandboxing", "slug": "docs/cli/sandbox" },
           { "label": "Settings", "slug": "docs/cli/settings" },
           { "label": "Telemetry", "slug": "docs/cli/telemetry" },
+          { "label": "Teleportation", "slug": "docs/cli/teleportation" },
           { "label": "Token caching", "slug": "docs/cli/token-caching" }
         ]
       },