@lucasschirm/claude-session-sync 0.1.1 → 0.2.2

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-session-sync",
-  "version": "0.1.2",
+  "version": "0.2.2",
   "description": "Sync Claude Code session data to S3-compatible storage.",
   "author": {
     "name": "lucasschirm"

package/README.md

@@ -149,6 +149,154 @@ bin/session-start        # SessionStart hook entry point
 bin/session-end          # SessionEnd hook entry point
 bin/hook                 # PreCompact/PostCompact/Stop/StopFailure/SubagentStop
 bin/transcript-watcher   # Detached watcher process spawned by session-start
+bin/claude-sync          # Standalone CLI for manual sync/list/download
+```
+
+## Standalone CLI
+
+In addition to the Claude Code hooks, this package ships a standalone CLI
+binary (`claude-sync`) that lets you manually upload, list, and download
+sessions from S3 storage. It's useful for backfilling historical sessions,
+inspecting what's been synced, or restoring sessions to a new machine.
+
+### Installation
+
+The CLI is included in the same npm package. You can run it via `npx` without
+installing anything:
+
+```bash
+npx @lucasschirm/claude-session-sync sync
+```
+
+Or install it globally for a shorter `claude-sync` command:
+
+```bash
+npm install -g @lucasschirm/claude-session-sync
+claude-sync sync
+```
+
+### Commands
+
+#### `sync`
+
+Upload all local Claude Code sessions for the current project to S3.
+
+```bash
+claude-sync sync
+```
+
+From the project directory, the CLI:
+
+1. Finds the corresponding Claude Code project folder in `~/.claude/projects/`.
+2. Lists all local `.jsonl` transcript files.
+3. For each session, checks if it already exists in S3 — if so, skips it.
+4. The first session uploaded captures workspace + global + session config.
+   Subsequent sessions capture only session-scoped transcripts (config is
+   uploaded once).
+5. Prints a per-session summary and a total.
+
+#### `list`
+
+List objects in the configured storage. Supports five forms:
+
+```bash
+# List all projects in storage
+claude-sync list
+
+# List sessions for the current project (requires SAL_PROJECT_ID)
+claude-sync list --current
+
+# List sessions for a specific project
+claude-sync list <project-id>
+
+# List files in a session
+claude-sync list <project-id> --session=<session-id>
+
+# List files under a session sub-path
+claude-sync list <project-id> --session=<session-id> --path=<path>
+```
+
+`--path` is relative to the session folder. For example, `--path=session` lists all files under the `session/` scope, and `--path=session/configs` lists files under that sub-path.
+
+Examples:
+
+```
+PROJECT ID        SESSIONS  FILES  SIZE       LAST MODIFIED
+-------------------------------------------------------------------------
+session-analyzer  12        410    84.3 MB    2026-08-18 19:36
+my-other-project  3         18     2.1 MB     2026-08-17 10:11
+
+2 project(s), 410 files, 86.4 MB total
+```
+
+```
+SESSION ID                              FILES  SIZE        LAST MODIFIED
+-------------------------------------------------------------------------
+d1acf718-cd8d-4c1d-84fd-b074d231995b    43     21.1 MB     2026-08-18 19:36
+test-summary-001                        8      119.6 KB    2026-08-18 19:35
+
+2 session(s), 51 files, 21.2 MB total
+```
+
+```
+KEY                                     SIZE       LAST MODIFIED
+-------------------------------------------------------------------------
+manifest.json                           2.4 KB     2026-08-18 19:36
+session/transcript.jsonl                1.1 MB     2026-08-18 19:36
+workspace/package.json                  3.2 KB     2026-08-18 19:35
+
+3 file(s), 1.1 MB total
+```
+
+#### `download`
+
+Download session files from S3 to a local directory.
+
+```bash
+# Download a specific session
+claude-sync download --session-id=<session-id> --output=<dir>
+
+# Download all sessions for the project
+claude-sync download all --output=<dir>
+```
+
+Files are restored to `<output>/<projectId>/<sessionId>/<scope>/<relativePath>`.
+
+### Configuration
+
+The CLI reads configuration from environment variables, falling back to
+`.claude/settings.local.json` `env` key for any variables not set in the
+process environment. This means you can configure it once in
+`.claude/settings.local.json` and the CLI will pick it up automatically.
+
+See the [Configuration](#configuration) section below for the full list of
+required and optional variables.
+
+If required variables are missing, the CLI prints an error with example
+`export` commands and a `.claude/settings.local.json` template:
+
+```
+Error: required configuration is missing or incomplete.
+
+The following environment variables must be set:
+  SAL_PROJECT_ID — Unique identifier for the project.
+  ...
+
+Set them via environment variables before running the CLI:
+
+  export SAL_PROJECT_ID=session-analyzer
+  export SAL_STORAGE_TYPE=s3
+  ...
+  npx @lucasschirm/claude-session-sync sync
+
+Or add them to .claude/settings.local.json:
+
+{
+  "env": {
+    "SAL_PROJECT_ID": "session-analyzer",
+    ...
+  }
+}
 ```
 
 ### Updating
@@ -188,8 +336,8 @@ shell before launching `claude`.
 | `SAL_STORAGE_TYPE`   | Storage backend. Currently only `s3` is supported.    |
 | `SAL_STORAGE_BUCKET` | S3 bucket name.                                       |
 | `SAL_STORAGE_REGION` | AWS region (e.g. `us-east-1`).                        |
-| `SAL_STORAGE_ID`     | AWS access key ID.                                    |
-| `SAL_STORAGE_SECRET` | AWS secret access key.                                |
+| `SAL_STORAGE_ACCESS_KEY_ID`     | AWS access key ID.                                    |
+| `SAL_STORAGE_SECRET_ACCESS_KEY` | AWS secret access key.                                |
 
 ### Optional
 
@@ -232,8 +380,8 @@ Edit `~/.claude/settings.json`:
     "SAL_STORAGE_TYPE": "s3",
     "SAL_STORAGE_BUCKET": "my-session-bucket",
     "SAL_STORAGE_REGION": "us-east-1",
-    "SAL_STORAGE_ID": "AKIAIOSFODNN7EXAMPLE",
-    "SAL_STORAGE_SECRET": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
+    "SAL_STORAGE_ACCESS_KEY_ID": "AKIAIOSFODNN7EXAMPLE",
+    "SAL_STORAGE_SECRET_ACCESS_KEY": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
   },
   "enabledPlugins": {
     "claude-session-sync@session-analyzer": true
@@ -253,8 +401,8 @@ gitignored by default, so credentials stay local):
     "SAL_STORAGE_TYPE": "s3",
     "SAL_STORAGE_BUCKET": "my-session-bucket",
     "SAL_STORAGE_REGION": "us-east-1",
-    "SAL_STORAGE_ID": "AKIAIOSFODNN7EXAMPLE",
-    "SAL_STORAGE_SECRET": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
+    "SAL_STORAGE_ACCESS_KEY_ID": "AKIAIOSFODNN7EXAMPLE",
+    "SAL_STORAGE_SECRET_ACCESS_KEY": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
     "SAL_STORAGE_ENDPOINT": "http://localhost:4566"
   }
 }
@@ -275,8 +423,8 @@ export SAL_PROJECT_ID="my-app"
 export SAL_STORAGE_TYPE="s3"
 export SAL_STORAGE_BUCKET="my-session-bucket"
 export SAL_STORAGE_REGION="us-east-1"
-export SAL_STORAGE_ID="AKIAIOSFODNN7EXAMPLE"
-export SAL_STORAGE_SECRET="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
+export SAL_STORAGE_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
+export SAL_STORAGE_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
 claude
 ```
 
@@ -293,8 +441,8 @@ For local testing without a real AWS account, run
     "SAL_STORAGE_BUCKET": "sal-sessions",
     "SAL_STORAGE_REGION": "us-east-1",
     "SAL_STORAGE_ENDPOINT": "http://localhost:4566",
-    "SAL_STORAGE_ID": "test",
-    "SAL_STORAGE_SECRET": "test"
+    "SAL_STORAGE_ACCESS_KEY_ID": "test",
+    "SAL_STORAGE_SECRET_ACCESS_KEY": "test"
   }
 }
 ```
@@ -340,6 +488,14 @@ packages/plugins/claude-session-sync/
 │   ├── session-start.ts     # SessionStart entry point
 │   ├── session-end.ts       # SessionEnd entry point
 │   ├── transcript-watcher.ts # Detached watcher spawner
+│   ├── cli.ts               # Standalone CLI entry point (claude-sync)
+│   ├── cli/                 # CLI command modules
+│   │   ├── env.ts           # Environment resolution (process.env + settings.local.json)
+│   │   ├── config.ts        # Config validation with example error messages
+│   │   ├── project.ts       # Claude project folder resolution
+│   │   ├── sync-command.ts  # "sync" command
+│   │   ├── list-command.ts  # "list" command
+│   │   └── download-command.ts # "download" command
 │   └── index.ts             # Public API barrel
 ├── bin/                     # Built executables (esbuild single-file bundles)
 ├── build.mjs                # esbuild bundling script