Add CLI commands for cloud snapshot management

[phernandez]

Summary

Add CLI commands to allow users to manage bucket snapshots from the bm command line tool.

Background

Basic Memory Cloud now supports Tigris bucket snapshots (PR basicmachines-co/basic-memory-cloud#346). Users should be able to manage snapshots via the CLI in addition to the web UI.

CLI Commands

Create snapshot

bm cloud snapshot create "before major refactor"
→ Created snapshot: snap_abc123 (2025-11-25T10:30:00)

List snapshots

bm cloud snapshot list
→ snap_abc123  "before major refactor"  2025-11-25  42 MB
→ snap_xyz789  "daily backup"           2025-11-24  41 MB

Delete snapshot

bm cloud snapshot delete snap_abc123
→ Deleted snapshot snap_abc123

Restore file from snapshot

bm cloud restore notes/project.md --snapshot snap_abc123
→ Restored notes/project.md from snapshot snap_abc123

Restore entire folder

bm cloud restore research/ --snapshot snap_abc123
→ Restored 12 files from research/

API Endpoints

The cloud service already exposes these endpoints:

• POST /api/bucket-snapshots - Create snapshot
• GET /api/bucket-snapshots - List snapshots
• GET /api/bucket-snapshots/{id} - Get snapshot details
• DELETE /api/bucket-snapshots/{id} - Delete snapshot
• GET /api/bucket-snapshots/{id}/browse?prefix= - Browse snapshot contents
• POST /api/bucket-snapshots/{id}/restore - Restore from snapshot

Implementation Notes

• Commands should be under bm cloud snapshot subgroup
• Restore command could be bm cloud restore or bm cloud snapshot restore
• Need to handle authentication (existing cloud auth flow)
• Consider adding --format json option for scripting

Related

• basicmachines-co/basic-memory-cloud#346 - SPEC-29: Tigris Bucket Versioning
• SPEC-29 in specs project for full details

[claude]

Claude finished @phernandez's task in 1m 23s —— View job

---

Issue Triage

• Analyze issue type and classification
• Check for duplicate issues
• Assess priority and complexity
• Add appropriate labels
• Provide triage summary

---

Analysis Summary

Issue Type: Feature Request / Enhancement

Classification:

• Component: CLI + Cloud functionality
• Priority: Medium
• Complexity: Medium

Details:

This is a well-defined feature request to add CLI commands for managing Tigris bucket snapshots. The cloud service already has the necessary API endpoints implemented (PR #346), so this is primarily a CLI integration task.

No Duplicates Found: This is the first issue requesting CLI commands for snapshot management.

Scope of Work:

The implementation would require:

1. New CLI command group: bm cloud snapshot with subcommands:

   • create - Create a new snapshot with optional description
   • list - Display all snapshots with metadata (name, date, size)
   • delete - Remove a snapshot by ID

2. Restore functionality: Either bm cloud restore or bm cloud snapshot restore:

   • File-level restore
   • Folder-level restore
   • Should update local files and trigger sync

3. Integration points:

   • Use existing cloud authentication flow (already implemented)
   • HTTP client calls to existing API endpoints
   • Rich console formatting for output
   • Optional --format json for scripting support

4. Testing:

   • Unit tests for command handlers
   • Integration tests with mock API responses
   • Consider adding to existing cloud command test suite

Existing Code Structure:

The codebase has a well-organized CLI structure under src/basic_memory/cli/commands/cloud/:

• core_commands.py - Login, logout, status, setup
• api_client.py - API request handling with auth
• Other cloud-specific functionality

The new snapshot commands would follow the same pattern, likely in a new snapshot_commands.py file.

Recommendation:

This is a straightforward feature that extends existing cloud functionality. The API endpoints are already available, making this primarily a CLI integration task. Implementation could proceed once confirmed that this aligns with the current roadmap priorities.

---

Labels Applied: enhancement

Would you like me to proceed with implementing these CLI commands?