{"id":30697478,"url":"https://github.com/tanmayvaij/snapcube","last_synced_at":"2025-09-02T09:09:57.576Z","repository":{"id":308854839,"uuid":"1034006329","full_name":"tanmayvaij/snapcube","owner":"tanmayvaij","description":"Snapcube  is a powerful CLI tool that allows you to save your project structure to JSON and recreate it anywhere. Perfect for project templates, backups, or sharing project scaffolds with your team.","archived":false,"fork":false,"pushed_at":"2025-08-31T06:56:51.000Z","size":56,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-31T06:57:27.248Z","etag":null,"topics":["ai-review","backup","code-scanning","code-structure","javascript","nodejs","project-template","scaffolding","snapshot","snapshot-testing","template","typescript"],"latest_commit_sha":null,"homepage":"https://snapcube.netlify.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tanmayvaij.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-07T17:29:32.000Z","updated_at":"2025-08-31T06:32:04.000Z","dependencies_parsed_at":"2025-08-08T13:17:34.482Z","dependency_job_id":null,"html_url":"https://github.com/tanmayvaij/snapcube","commit_stats":null,"previous_names":["tanmayvaij/clonecube","tanmayvaij/snapcube"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/tanmayvaij/snapcube","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tanmayvaij%2Fsnapcube","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tanmayvaij%2Fsnapcube/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tanmayvaij%2Fsnapcube/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tanmayvaij%2Fsnapcube/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tanmayvaij","download_url":"https://codeload.github.com/tanmayvaij/snapcube/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tanmayvaij%2Fsnapcube/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273258307,"owners_count":25073659,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-02T02:00:09.530Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-review","backup","code-scanning","code-structure","javascript","nodejs","project-template","scaffolding","snapshot","snapshot-testing","template","typescript"],"created_at":"2025-09-02T09:09:56.669Z","updated_at":"2025-09-02T09:09:57.559Z","avatar_url":"https://github.com/tanmayvaij.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# **Snapcube**\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) ![npm](https://img.shields.io/npm/dw/snapcube)\n\n📖 Full Documentation → [https://snapcube.netlify.app](https://snapcube.netlify.app)\n\n\u003e **Clone and recreate complete project structures in seconds!** 🚀\n\nSnapcube is a **lightweight CLI tool** that snapshots your project's **entire directory tree** (including or excluding file contents) into a single JSON file — and recreates it anywhere instantly.\nPerfect for **templates**, **backups**, **AI-assisted reviews**, and **team sharing**.\n\n---\n\n## ✨ **Features**\n\n* 📦 **Local Project Cloning** – Save your project's structure and contents into JSON\n* 🌐 **GitHub Repo Cloning** – Fetch any public GitHub repository directly into JSON (no manual download needed)\n* 🦊 **GitLab Repo Cloning** – Fetch GitLab repositories with full support for public and private repos\n* 🔑 **Private Repo Cloning** – Clone **private GitHub/GitLab repositories** by passing a Personal Access Token (`--token`)\n* 🏗 **Project Creation** – Rebuild projects exactly from saved JSON\n* 🚫 **Smart Filtering** – Skips unnecessary directories like `node_modules`\n* 🔄 **Recursive Scanning** – Handles deeply nested folder structures\n* 📝 **Content Control** – Choose to include **all**, **only non-binary**, or **no** file contents\n* 📂 **Structure-Only Mode** – Return only an **array of file paths** (no metadata/contents) — lightweight for AI/LLM project analysis\n* ⚡ **Fast \u0026 Efficient** – Minimal disk and memory overhead\n* ✅ **Validation** – Detects and warns if a `.snapcube.json` is invalid before creation\n\n---\n\n## 📦 **Installation**\n\n### **Global Install (recommended for frequent use)**\n\n```bash\nnpm install -g snapcube\n```\n\nThen use it anywhere:\n\n```bash\nsnapcube clone ./my-project\n```\n\n---\n\n### **Using Without Installation (`npx`)**\n\nIf you don't want to install globally, you can run Snapcube directly:\n\n```bash\nnpx snapcube clone ./my-project\n```\n\n💡 **Notes for `npx` usage**:\n\n* On first run, `npx` downloads the package temporarily.\n* You **must** have Node.js installed (version 18+ recommended).\n* If you get `command not found`, try again — sometimes the first run only fetches dependencies.\n\n**Example workflow with `npx`**:\n\n```bash\n# Clone a project structure without binary contents\nnpx snapcube clone ./my-project --ignore-binaries\n\n# Restore it later\nnpx snapcube create my-project.snapcube.json\n```\n\n---\n\n## 🚀 **Usage Examples**\n\n### **1. Clone a Local Project**\n\n```bash\nsnapcube clone \u003cdirectory-path\u003e\n```\n\nExample:\n\n```bash\nsnapcube clone ./my-awesome-project\n```\n\nThis will generate:\n\n```\nmy-awesome-project.snapcube.json\n```\n\n---\n\n### **2. Clone a GitHub Repository**\n\n```bash\nsnapcube clone-repo github:\u003cusername/repo\u003e@\u003cbranch\u003e\n```\n\nExamples:\n\n```bash\n# Clone Snapcube repo itself (main branch)\nsnapcube clone-repo github:tanmayvaij/snapcube@main\n\n# Clone without binary file contents\nsnapcube clone-repo github:tanmayvaij/artistly@main --ignore-binaries\n\n# Clone only structure (no file contents)\nsnapcube clone-repo github:tanmayvaij/artistly@main --ignore-all\n```\n\n📄 Generates `{username}_{repo-name}.snapcube.json`.\n\n---\n\n### **3. Clone a GitLab Repository**\n\n```bash\nsnapcube clone-repo gitlab:\u003cusername/repo\u003e@\u003cbranch\u003e\n```\n\nExamples:\n\n```bash\n# Clone a GitLab repo\nsnapcube clone-repo gitlab:username/my-project@main\n\n# Clone with authentication token\nsnapcube clone-repo gitlab:username/private-project@main --token \u003cyour_gitlab_token\u003e\n```\n\n---\n\n### **🔑 Clone a Private Repository**\n\nPrivate repositories require authentication with a **Personal Access Token**.\n\n```bash\nsnapcube clone-repo github:username/private-repo@main --token \u003cyour_github_token\u003e\nsnapcube clone-repo gitlab:username/private-repo@main --token \u003cyour_gitlab_token\u003e\n```\n\nExamples:\n\n```bash\n# Clone a private GitHub repo fully\nsnapcube clone-repo github:myorg/secret-project@main --token ghp_xxx123abc\n\n# Clone private GitLab repo but skip binary files\nsnapcube clone-repo gitlab:myorg/secret-project@main --ignore-binaries --token glpat_xxx123abc\n```\n\n⚠️ If you try cloning a private repo without `--token`, Snapcube will throw an error.\n\n👉 **How to generate tokens**:\n\n**GitHub:**\n1. Go to [GitHub Settings → Developer Settings → Personal Access Tokens](https://github.com/settings/tokens).\n2. Click **Generate new token** → Choose **classic token**.\n3. Select scopes: `repo` (to access private repos)\n\n**GitLab:**\n1. Go to GitLab Settings → Access Tokens\n2. Create token with `read_repository` scope\n\n---\n\n### **4. Recreate a Project**\n\n```bash\nsnapcube create \u003cjson-file\u003e\n```\n\nExample:\n\n```bash\nsnapcube create my-awesome-project.snapcube.json\n```\n\nThe project will be recreated inside a folder named after the original project.\n\n---\n\n### **5. Structure-Only Mode**\n\nIf you only want the **directory tree** (without file contents, sizes, encodings, etc.), use `--structure-only`.\n\n```bash\nsnapcube clone ./my-project --structure-only\n```\n\nExample Output:\n\n```json\n[\n  \"my-project/package.json\",\n  \"my-project/src/index.js\",\n  \"my-project/src/App.jsx\",\n  \"my-project/public/index.html\"\n]\n```\n\nThis is extremely useful for **AI/LLM project understanding**, **lightweight snapshots**, or **tech stack analysis**.\n\n---\n\n## 📋 **Commands \u0026 Flags**\n\n| Command / Option    | Description                                                       | Example                                                      |\n| ------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------ |\n| `clone`             | Save local project structure to JSON                              | `snapcube clone ./my-project`                                |\n| `clone-repo`        | Save structure of a **remote repo** to JSON                       | `snapcube clone-repo github:user/repo@main`                  |\n| `create`            | Restore project from JSON                                         | `snapcube create my-project.snapcube.json`                   |\n| `--ignore-binaries` | Ignore content of binary files (images, PDFs, videos, etc.)       | `snapcube clone ./my-project --ignore-binaries`              |\n| `--ignore-all`      | Ignore content of **all files** — only structure \u0026 metadata saved | `snapcube clone ./my-project --ignore-all`                   |\n| `--structure-only`  | Save **only the file paths** (no metadata/contents)               | `snapcube clone ./my-project --structure-only`               |\n| `--token \u003ctoken\u003e`   | Provide authentication token for **private repos**                | `snapcube clone-repo github:user/private@main --token xxx`   |\n| `--help`            | Show help information                                             | `snapcube --help`                                            |\n| `--version`         | Show version number                                               | `snapcube --version`                                         |\n\n💡 **Tip:** If both `--ignore-all` and `--ignore-binaries` are provided, `--ignore-all` takes priority.\n💡 **Note:** `--structure-only` overrides everything else and just outputs an array of file paths.\n\n---\n\n## 📁 **JSON File Structure**\n\nExample output:\n\n```json\n[\n  {\n    \"fileName\": \"package.json\",\n    \"filePath\": \"my-awesome-project\",\n    \"content\": \"{\\n  \\\"name\\\": \\\"my-project\\\"...\\n}\",\n    \"isBinary\": false,\n    \"encoding\": \"utf-8\"\n  },\n  {\n    \"fileName\": \"logo.png\",\n    \"filePath\": \"my-awesome-project/assets\",\n    \"content\": null,\n    \"isBinary\": true,\n    \"encoding\": \"base64\"\n  }\n]\n```\n\n📌 **Structure-only mode** simplifies this to just file paths:\n\n```json\n[\n  \"my-awesome-project/package.json\",\n  \"my-awesome-project/assets/logo.png\"\n]\n```\n\n---\n\n## 🎯 **Use Cases**\n\n* 📋 **Project Templates** – Distribute starter kits instantly\n* 🔄 **Backup \u0026 Restore** – Keep lightweight project backups\n* 🌐 **Clone Remote Repos to JSON** – Store snapshots for later use\n* 🔑 **Private Repo Snapshots** – Archive or share internal projects securely\n* 🤝 **Collaboration** – Share codebases without using Git\n* 📚 **Education** – Distribute coding examples \u0026 tutorials\n* 🤖 **AI Code Review** – Send `.snapcube.json` for AI-assisted debugging\n* 🧠 **LLM Project Analysis** – Use `--structure-only` to let AI quickly identify frameworks, languages, and project setup\n\n---\n\n## ⚙️ **How It Works**\n\n### **Cloning Process**\n\n1. Scans the target directory or remote repo recursively\n2. Skips ignored folders (`node_modules`, `.git`, etc.)\n3. Reads file content (Base64 for binary, UTF-8 for text) unless ignored\n4. Saves everything to a `.snapcube.json` file\n\n### **Creation Process**\n\n1. Validates the `.snapcube.json` format\n2. Creates necessary folders\n3. Restores files with their original content (if available)\n4. Recreates the exact directory structure\n\n---\n\n## 🚫 **Ignored by Default**\n\n* `node_modules/`\n* `.git/` and hidden directories\n* `.next/`, `dist/`, `out/`, and build output folders\n* `__pycache__/`, `venv/`, `vender/`\n* Temporary files like `.DS_Store`, `thumbs.db`, and cache directories\n\n---\n\n## 🤝 **Contributing**\n\n1. 🍴 Fork the repo\n2. 🌱 Create a branch: `git checkout -b feature/AmazingFeature`\n3. 💾 Commit changes: `git commit -m \"Add some AmazingFeature\"`\n4. 📤 Push: `git push origin feature/AmazingFeature`\n5. 🎉 Open a Pull Request\n\n---\n\n## 🐛 **Issues \u0026 Support**\n\n* 🐞 [Report a Bug](https://github.com/tanmayvaij/snapcube/issues)\n* 💡 [Request a Feature](https://github.com/tanmayvaij/snapcube/issues/new)\n* 📧 Email: **[tanmayvaij22@gmail.com](mailto:tanmayvaij22@gmail.com)**\n\n---\n\n## 🙏 **Acknowledgments**\n\n* Built with ❤️ using Node.js + Commander.js\n* Inspired by the need for quick project structure sharing\n* Thanks to all contributors and early adopters\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**⭐ If you like Snapcube, star the repo to support development!**\n\nMade with 💖 by [Tanmay Vaij](https://github.com/tanmayvaij)\n\n\u003c/div\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftanmayvaij%2Fsnapcube","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftanmayvaij%2Fsnapcube","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftanmayvaij%2Fsnapcube/lists"}