\n\n## Installation\n\n```bash\nnpm install -g shov\n```\n\n## Quick Start\n\n### 1. Create a new project\n\n```bash\n# Create an anonymous project (default: creates ./shov/ directory with starter files)\nshov new\n\n# Create a named project\nshov new my-project\n\n# Create a project with email verification (for account management)\nshov new my-project --email user@example.com\n\n# Use TypeScript instead of JavaScript\nshov new my-project --lang ts\nshov new my-project --typescript # shorthand\n\n# Custom code directory location\nshov new my-project --code-dir . # Current directory (like Next.js)\nshov new my-project --code-dir ./backend # Custom directory\nshov new my-project --code-dir ./api # Another custom location\n\n# Create project on server only (no local files)\nshov new my-project --remote-only\nshov new my-project --no-local # alias\n\n# Combined options\nshov new my-project --ts --code-dir ./backend --email user@example.com\n\n# With starter templates (recommended syntax)\nshov new my-app --b2c --ts --code-dir ./shov\nshov new my-saas --b2b --ts --code-dir ./backend\n\n# With starter templates + frontend (auto-configured!)\nshov new my-app --b2c --react # B2C + React (VITE_SHOV_URL in .env)\nshov new my-app --b2c --ts --vue # B2C + TypeScript + Vue\nshov new my-saas --b2b --nextjs # B2B + Next.js (NEXT_PUBLIC_SHOV_URL in .env.local)\nshov new my-saas --b2b --ts --nextjs # B2B + TypeScript + Next.js\n```\n\nThis will:\n- Create a new Shov project (anonymous by default)\n- Generate an API key\n- **Download starter files** to local directory (default: `./shov/`)\n- Save configuration to `.shov` file (includes project, API key, org, URL)\n- Add environment variables to your `.env` file (includes `SHOV_PROJECT`, `SHOV_API_KEY`, `SHOV_ORG`, `SHOV_URL`)\n- If email is provided, send a verification code for account linking\n\n### Claiming Anonymous Projects\n\nIf you created a project anonymously, you can claim it later to manage it from your dashboard:\n\n```bash\n# Claim an anonymous project\nshov claim my-anonymous-project user@example.com\n\n# The CLI will:\n# 1. Send a verification code to your email\n# 2. Prompt you to enter the code\n# 3. Complete the claim process\n```\n\nThis allows you to:\n- Access the project from the Shov dashboard\n- Manage team members and permissions\n- View usage analytics and billing\n\n### 2. Store and retrieve data\n\n```bash\n# Set a key-value pair\nshov set hello \"world\"\n\n# Get a value\nshov get hello\n\n# Store JSON data\nshov set user '{\"name\":\"Alice\",\"age\":25}'\n```\n\n### 3. Work with collections\n\n```bash\n# Add items to a collection\nshov add users '{\"name\":\"Alice\",\"age\":25,\"role\":\"admin\"}'\nshov add users '{\"name\":\"Bob\",\"age\":30,\"role\":\"user\"}'\n\n# Find items with advanced filters\nshov where users -f '{\"age\":25}'\nshov where users -f '{\"age\": {\"$gte\": 18}, \"role\": {\"$in\": [\"admin\", \"moderator\"]}}'\nshov where users -f '{\"name\": {\"$like\": \"A%\"}, \"age\": {\"$between\": [20, 35]}}'\n\n# Count items in collections\nshov count users\nshov count users -f '{\"role\": \"admin\"}'\nshov count users -f '{\"age\": {\"$gte\": 18}, \"status\": \"active\"}'\n\n# Find all items in a collection\nshov where users\n```\n\n## Commands\n\n### Project Management\n\n- `shov new [projectName]` - Create a new Shov project and API key\n - `--email ` - Link project to your email (requires verification)\n- `shov claim ` - Claim an anonymous project by associating it with your email\n- `shov config` - Show current project configuration\n\n### Data Operations\n\n- `shov set ` - Set a key-value pair\n- `shov get ` - Get a value by key\n- `shov forget ` - Delete a key-value pair\n- `shov add ` - Add an item to a collection\n- `shov where ` - Find items in a collection (returns all if no filter)\n- `shov count ` - Count items in a collection with optional filtering\n- `shov add-many ` - Add multiple items to a collection at once\n- `shov update ` - Update an item by collection and ID\n- `shov remove ` - Remove an item from a collection by ID\n- `shov clear ` - Clear all items from a collection\n- `shov batch ` - Execute multiple operations atomically in a single transaction\n- `shov contents` - List all memory contents (keys, collections, files)\n\n### File Operations\n- `shov upload ` - Upload a file\n- `shov upload-url ` - Generate a pre-signed URL for client-side uploads\n- `shov forget-file ` - Delete a file by filename\n\n### Authentication\n- `shov send-otp ` - Send a verification code to an email\n- `shov verify-otp ` - Verify an email with a code\n\n### Real-time Streaming\n- `shov token streaming ` - Create a streaming token for browser-side connections\n- `shov subscribe ` - Subscribe to real-time updates via Server-Sent Events\n- `shov broadcast ` - Broadcast a message to active subscribers\n\n### Code Functions\n- `shov code list` - List all deployed code files\n- `shov code write ` - Write (create or overwrite) a code file deployed to the global edge network\n- `shov code read ` - Read the source code of a deployed code file\n- `shov code pull` - Download all code files from your project to local directory\n- `shov code delete ` - Delete a code file from the global network\n- `shov code rollback [version]` - Rollback a code file to a previous version\n- `shov code logs [name]` - View real-time logs from your code functions\n\n### Secrets Management\n- `shov secrets list` - List all secret names (values never shown for security)\n- `shov secrets set ` - Set a secret for code functions\n- `shov secrets set-many ` - Set multiple secrets at once (bulk operation)\n- `shov secrets delete ` - Delete a secret from code functions\n\n### Backup & Restore (Time-Travel)\n- `shov restore` - Restore your backend from a backup\n - `--from ` - When to restore from (e.g., \"2 hours ago\", \"2024-10-01 14:30\")\n - `--to ` - Target environment (default: current)\n - `--to-new-env ` - Create new environment from backup\n - `--code` - Restore only code files\n - `--data` - Restore only data\n - `--files` - Restore only uploaded files\n - `--secrets` - Restore only secrets\n - `--all` - Restore everything (default if no flags)\n - `-y, --yes` - Skip confirmation prompts\n- `shov clone ` - Clone entire environment (code, data, files, secrets)\n - `-y, --yes` - Skip confirmation prompts\n- `shov history` - View backup history\n - `--env ` - Filter by environment (default: production)\n - `--type ` - Filter by type (code, data, files, secrets)\n - `--limit ` - Number of backups to show (default: 50)\n - `--json` - Output JSON for scripting\n- `shov rollback` - Quick rollback to 1 hour ago (shortcut for restore)\n - `--from ` - Override default (1 hour ago)\n - `--to ` - Target environment\n - `-y, --yes` - Skip confirmation prompts\n\n### Options\n\nAll data commands support these options:\n- `-p, --project ` - Specify project name\n- `-k, --key ` - Specify API key\n- `--json` - Output structured JSON for scripting (available on get, where commands)\n- `--limit ` - Alias for --top-k (pagination)\n- `--offset ` - Skip results for pagination\n\nIf project/key not provided, values are read from `.shov` configuration file.\n\n## Configuration\n\nThe CLI stores configuration in a `.shov` file in your project directory:\n\n```json\n{\n \"project\": \"my-app\",\n \"apiKey\": \"sk_live_...\",\n \"email\": \"you@example.com\"\n}\n```\n\n## Examples\n\n### Basic Key-Value Storage\n\n```bash\n# String values\nshov set app_name \"My Awesome App\"\nshov get app_name\n\n# JSON values\nshov set config '{\"theme\":\"dark\",\"lang\":\"en\"}'\nshov get config\n```\n\n### Collections\n\n```bash\n# Add users\nshov add users '{\"id\":1,\"name\":\"Alice\",\"role\":\"admin\"}'\nshov add users '{\"id\":2,\"name\":\"Bob\",\"role\":\"user\"}'\n\n# Add multiple users at once\nshov add-many users '[\n {\"id\":3,\"name\":\"Charlie\",\"role\":\"user\"},\n {\"id\":4,\"name\":\"Diana\",\"role\":\"admin\"}\n]'\n\n# Find users with specific roles\nshov where users -f '{\"role\":\"admin\"}'\n\n# Get all users (no filter)\nshov where users\n\n# Update a user by collection and ID\nshov update users user-id-123 '{\"name\":\"Alice Smith\",\"role\":\"super-admin\"}'\n\n# Remove a user by collection and ID\nshov remove users user-id-123\n\n# View all contents\nshov contents\n\n# Clear all users\nshov clear users\n```\n\n### File Operations\n\n```bash\n# Upload a file directly\nshov upload ./document.pdf\n\n# Generate a pre-signed URL for client-side uploads\nshov upload-url document.pdf\n\n# Delete a file\nshov forget-file document.pdf\n```\n\n### Filtered Queries\n\n```bash\n# Add some test data\nshov add-many products '[\n {\"name\":\"Fender Stratocaster\",\"type\":\"Electric Guitar\",\"price\":1299},\n {\"name\":\"Roland TD-27KV\",\"type\":\"Electronic Drums\",\"price\":2499}\n]'\n\n# Query with filters\nshov where products --filter '{\"type\":\"Electric Guitar\"}'\nshov where products --filter '{\"price\": {\"$between\": [100, 500]}}'\nshov where products --filter '{\"price\": {\"$gte\": 1000}}'\n\n# Get structured JSON output for scripting\nshov where products --filter '{\"type\":\"Electric Guitar\"}' --json\n```\n\n### Authentication\n\n```bash\n# Get a login code\nshov send-otp user@example.com\n\n# Verify the code\nshov verify-otp user@example.com 123456\n```\n\n### Atomic Transactions\n\n```bash\n# Execute multiple operations atomically\nshov batch '[\n {\"type\": \"set\", \"name\": \"user:123\", \"value\": {\"name\": \"John\", \"email\": \"john@example.com\"}},\n {\"type\": \"add\", \"collection\": \"orders\", \"value\": {\"userId\": \"123\", \"total\": 99.99}},\n {\"type\": \"update\", \"collection\": \"inventory\", \"id\": \"item-456\", \"value\": {\"stock\": 10}}\n]'\n\n# E-commerce checkout example (atomic transaction)\nshov batch '[\n {\"type\": \"add\", \"collection\": \"orders\", \"value\": {\"userId\": \"123\", \"items\": [{\"id\": \"prod-1\", \"qty\": 2}], \"total\": 199.98}},\n {\"type\": \"update\", \"collection\": \"inventory\", \"id\": \"prod-1\", \"value\": {\"stock\": 8}},\n {\"type\": \"set\", \"name\": \"user:123:last_order\", \"value\": \"order-abc123\"}\n]'\n\n# Read-your-writes consistency\nshov batch '[\n {\"type\": \"set\", \"name\": \"counter\", \"value\": 1},\n {\"type\": \"get\", \"name\": \"counter\"},\n {\"type\": \"set\", \"name\": \"counter\", \"value\": 2}\n]' --json\n```\n\n**Supported operation types in batch:**\n- `set` - Set key-value pairs\n- `get` - Read values (for read-your-writes consistency)\n- `add` - Add items to collections\n- `update` - Update collection items by ID\n- `remove` - Remove collection items by ID\n- `forget` - Delete keys\n- `clear` - Clear entire collections\n\n**⚠️ Important**: All operations in a batch are executed atomically. If any operation fails, the entire batch is rolled back and no changes are made.\n\n### Real-time Streaming\n\n```bash\n# Create a streaming token for browser-side connections\nshov token streaming '[\n {\"collection\": \"users\", \"filters\": {\"status\": \"active\"}},\n {\"key\": \"config\"},\n {\"channel\": \"notifications\"}\n]' --expires 3600\n\n# Subscribe to real-time updates (keeps connection open)\nshov subscribe '[\n {\"collection\": \"users\"},\n {\"key\": \"config\"},\n {\"channel\": \"chat\"}\n]'\n# This will show live updates as they happen. Press Ctrl+C to stop.\n\n# In another terminal, broadcast messages to subscribers\nshov broadcast '{\"channel\": \"chat\"}' '{\"user\": \"Alice\", \"message\": \"Hello everyone!\"}'\n\n# Broadcast to collection subscribers\nshov broadcast '{\"collection\": \"users\", \"filters\": {\"role\": \"admin\"}}' '{\"type\": \"alert\", \"text\": \"System maintenance\"}'\n\n# Broadcast to key subscribers\nshov broadcast '{\"key\": \"config\"}' '{\"theme\": \"dark\", \"updated_at\": \"2024-01-15T10:30:00Z\"}'\n```\n\n**Real-time Features:**\n- **Collection Subscriptions**: Get notified when items are added, updated, or removed\n- **Key Subscriptions**: Real-time updates when specific keys change\n- **Custom Channels**: Send and receive custom messages for chat, notifications, etc.\n- **Filtered Subscriptions**: Only receive updates matching your criteria\n- **Auto-broadcasts**: All data writes (set, add, update, remove) automatically notify subscribers\n\n### Code Functions\n\n```bash\n# List all deployed code files\nshov code list\n\n# Write a code file (creates new or overwrites existing)\necho 'export default async function(req) { \n return new Response(JSON.stringify({ message: \"Hello from the edge!\" })); \n}' > index.js\nshov code write index.js index.js\n\n# Read a code file's source\nshov code read index.js\n\n# Pull all code files to local directory\nshov code pull\n# Downloads: index.js, routes.js, routes/*, services/*, etc.\n\n# Pull to specific directory\nshov code pull --output ./my-code/\n\n# Update by writing again (overwrite)\nshov code write index.js index-v2.js\n\n# View real-time logs\nshov code logs\n\n# Rollback to previous version\nshov code rollback index.js\n\n# Delete a code file\nshov code delete index.js\n```\n\n### Secrets Management\n\n```bash\n# List all secret names\nshov secrets list\n\n# Set a secret for all functions\nshov secrets set DATABASE_URL \"postgresql://user:pass@localhost:5432/db\"\n\n# Set a secret for specific functions\nshov secrets set API_KEY \"sk_live_abc123\" --functions \"user-auth,payment-api\"\n\n# Set multiple secrets at once\nshov secrets set-many '[\n {\"name\": \"DATABASE_URL\", \"value\": \"postgresql://user:pass@localhost:5432/db\"},\n {\"name\": \"REDIS_URL\", \"value\": \"redis://localhost:6379\"},\n {\"name\": \"JWT_SECRET\", \"value\": \"super-secret-jwt-key\"}\n]'\n\n# Delete a secret\nshov secrets delete OLD_API_KEY\n```\n\n### JSON Output & Scripting\n\nUse `--json` flag for structured output suitable for automation:\n\n```bash\n# Get structured JSON output\nshov get config --json\n# Output: {\"success\": true, \"key\": \"config\", \"value\": {...}, \"project\": \"my-project\"}\n\n# Query with JSON output for parsing\nshov where products --filter '{\"category\":\"electronics\"}' --json | jq '.items[].value.name'\n\n# Pipe results to other tools\nshov where users --json | jq '.items | length' # Count users\n\n# Use in shell scripts\nRESULT=$(shov get user_count --json)\nif echo \"$RESULT\" | jq -e '.success' > /dev/null; then\n COUNT=$(echo \"$RESULT\" | jq -r '.value')\n echo \"Current user count: $COUNT\"\nfi\n```\n\n### Integration with Existing Projects\n\n```bash\n# Initialize in existing project (less common)\ncd my-existing-project\nshov init --project my-project --key shov_live_...\n\n# Or use environment variables\nexport SHOV_PROJECT=my-project\nexport SHOV_API_KEY=shov_live_...\nshov get some_key\n```\n\n## JavaScript SDK\n\nFor programmatic access, use the Shov JavaScript SDK:\n\n```bash\nnpm install shov-js\n```\n\n```javascript\nimport { Shov } from 'shov-js'\n\nconst shov = new Shov({\n project: 'my-project',\n apiKey: 'shov_live_...'\n})\n\n// Key-value operations\nawait shov.set('hello', 'world')\nconst value = await shov.get('hello')\nawait shov.forget('hello')\n\n// Collections\nawait shov.add('users', { name: 'Alice', age: 25 })\nconst users = await shov.where('users', { filter: { age: 25 } })\n\n// Filtered queries\nconst results = await shov.where('users', { filter: { name: 'Alice' } })\n\n// Atomic transactions\nconst batchResult = await shov.batch([\n { type: 'set', name: 'user:123', value: { name: 'John', email: 'john@example.com' } },\n { type: 'add', collection: 'orders', value: { userId: '123', total: 99.99 } },\n { type: 'update', collection: 'inventory', id: 'item-456', value: { stock: 10 } }\n])\n\n// Real-time streaming\nconst { eventSource, close } = await shov.subscribe([\n { collection: 'users' },\n { channel: 'notifications' }\n], {\n onMessage: (data) => console.log('Update:', data),\n onError: (error) => console.error('Stream error:', error)\n})\n\n// Broadcast messages\nawait shov.broadcast(\n { channel: 'notifications' },\n { text: 'Hello from the app!' }\n)\n\n// Close stream when done\n// close()\n```\n\n### Backup & Restore Examples\n\n```bash\n# View backup history\nshov history\n\n# Restore from 2 hours ago (natural language!)\nshov restore --from \"2 hours ago\"\n\n# Restore to specific timestamp\nshov restore --from \"2024-10-01 14:30:00\"\n\n# Quick emergency rollback\nshov rollback --yes\n\n# Restore only code to staging\nshov restore --from \"2 hours ago\" --code --to staging\n\n# Create debug environment from yesterday\nshov restore --from \"1 day ago\" --to-new-env \"debug-yesterday\"\n\n# Clone production to staging\nshov clone production staging\n\n# Clone with immediate confirmation\nshov clone production staging --yes\n\n# View specific environment history\nshov history --env production --type code --limit 100\n\n# Interactive restore (no flags needed)\nshov restore\n# CLI will prompt you for:\n# - When to restore from\n# - What to restore (code/data/files/secrets)\n# - Where to restore to\n```\n\n**Natural Language Timestamps:**\n- `\"2 hours ago\"`, `\"30 minutes ago\"`\n- `\"3 days ago\"`, `\"1 week ago\"`\n- `\"last tuesday\"`, `\"yesterday\"`\n- Or use exact: `\"2024-10-01 14:30:00\"`\n\n**Selective Restore:**\n```bash\n# Just code + secrets\nshov restore --from \"2 hours ago\" --code\n\n# Just data\nshov restore --from \"1 day ago\" --data\n\n# Just files\nshov restore --from \"3 days ago\" --files\n\n# Everything\nshov restore --from \"2 hours ago\" --all\n```\n\n## Next.js Integration\n\nCreate a new Next.js app with Shov pre-configured:\n\n```bash\nnpx create-next-app@latest my-app --use-npm\ncd my-app\nshov init\nnpm install shov-js\n```\n\nThen use in your app:\n\n```javascript\n// lib/shov.js\nimport { Shov } from 'shov-js'\n\nexport const shov = new Shov({\n project: process.env.SHOV_PROJECT,\n apiKey: process.env.SHOV_API_KEY\n})\n\n// pages/api/users.js\nimport { shov } from '../../lib/shov'\n\nexport default async function handler(req, res) {\n if (req.method === 'POST') {\n const user = await shov.add('users', req.body)\n res.json(user)\n } else {\n // Example: find users matching a query parameter\n const users = await shov.where('users', { filter: req.query })\n res.json(users)\n }\n}\n```\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/shovdev/shov-cli/issues)\n\n## License\n\nMIT\n","readmeFilename":"README.md"}
![\"GitHub\"](\"https://img.shields.io/badge/GitHub-181717?style=flat&logo=github&logoColor=white\"){kind=icon}
•\n ![\"X\"](\"https://img.shields.io/badge/X-000000?style=flat&logo=x&logoColor=white\"){kind=icon}
•\n ![\"Reddit\"](\"https://img.shields.io/badge/Reddit-FF4500?style=flat&logo=reddit&logoColor=white\"){kind=icon}
•\n ![\"Discord\"](\"https://img.shields.io/badge/Discord-5865F2?style=flat&logo=discord&logoColor=white\"){kind=icon}
\n