{"id":32368881,"url":"https://github.com/glinharesb/vtex-files-manager","last_synced_at":"2026-04-13T18:01:16.024Z","repository":{"id":320440478,"uuid":"1081990835","full_name":"glinharesb/vtex-files-manager","owner":"glinharesb","description":"VTEX file upload CLI tool with GraphQL and CMS FilePicker support.","archived":false,"fork":false,"pushed_at":"2025-10-23T19:51:45.000Z","size":39,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-23T21:07:28.492Z","etag":null,"topics":["cli","cms","file-manager","files","golang","graphql","npm","upload","vtex","vtex-cli"],"latest_commit_sha":null,"homepage":"","language":"Go","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/glinharesb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-23T15:19:24.000Z","updated_at":"2025-10-23T19:51:48.000Z","dependencies_parsed_at":"2025-10-23T21:07:43.468Z","dependency_job_id":"9fb70cb5-18bf-4ce5-b311-ef0fa0cc07fb","html_url":"https://github.com/glinharesb/vtex-files-manager","commit_stats":null,"previous_names":["glinharesb/vtex-files-manager"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/glinharesb/vtex-files-manager","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glinharesb%2Fvtex-files-manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glinharesb%2Fvtex-files-manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glinharesb%2Fvtex-files-manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glinharesb%2Fvtex-files-manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/glinharesb","download_url":"https://codeload.github.com/glinharesb/vtex-files-manager/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glinharesb%2Fvtex-files-manager/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31764317,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T15:25:13.801Z","status":"ssl_error","status_checked_at":"2026-04-13T15:25:09.162Z","response_time":93,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["cli","cms","file-manager","files","golang","graphql","npm","upload","vtex","vtex-cli"],"created_at":"2025-10-24T19:35:13.745Z","updated_at":"2026-04-13T18:01:15.988Z","avatar_url":"https://github.com/glinharesb.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# VTEX Files Manager\n\n[![CI](https://github.com/glinharesb/vtex-files-manager/workflows/CI/badge.svg)](https://github.com/glinharesb/vtex-files-manager/actions?query=workflow%3ACI)\n[![Release](https://github.com/glinharesb/vtex-files-manager/workflows/Release/badge.svg)](https://github.com/glinharesb/vtex-files-manager/actions?query=workflow%3ARelease)\n[![Go Version](https://img.shields.io/github/go-mod/go-version/glinharesb/vtex-files-manager)](https://github.com/glinharesb/vtex-files-manager/blob/main/go.mod)\n[![License](https://img.shields.io/github/license/glinharesb/vtex-files-manager)](LICENSE)\n[![Latest Release](https://img.shields.io/github/v/release/glinharesb/vtex-files-manager)](https://github.com/glinharesb/vtex-files-manager/releases/latest)\n\n**vfm** - A powerful CLI tool for uploading images and files to VTEX, integrated with VTEX CLI.\n\n## Features\n\n- ✅ Single file or batch upload\n- ✅ Automatic integration with VTEX CLI (uses `vtex login` session)\n- ✅ Two upload methods: GraphQL (official) and CMS FilePicker (legacy)\n- ✅ Automatic check for existing files\n- ✅ Confirmation prompt before overwriting\n- ✅ URL encoding for names with spaces and special characters\n- ✅ Configurable concurrent uploads\n- ✅ Recursive subdirectory support\n- ✅ Progress bar during upload\n- ✅ Upload history with logs command\n\n## Prerequisites\n\n- [VTEX CLI](https://developers.vtex.com/docs/guides/vtex-io-documentation-vtex-io-cli-install) installed\n- Authenticated session in VTEX CLI (`vtex login`)\n\n## Installation\n\n### Option 1: npm (Recommended)\n\n```bash\nnpm install -g vtex-files-manager\n```\n\nThe `vfm` command will be available globally.\n\n### Option 2: Direct Binary Download\n\nDownload the `vfm` binary for your operating system from the [releases page](https://github.com/glinharesb/vtex-files-manager/releases/latest):\n\n#### **Linux**\n```bash\n# Download (replace VERSION with desired version, e.g., 1.0.0)\nwget https://github.com/glinharesb/vtex-files-manager/releases/download/vVERSION/vtex-files-manager_VERSION_Linux_x86_64.tar.gz\n\n# Extract\ntar -xzf vtex-files-manager_VERSION_Linux_x86_64.tar.gz\n\n# Move to PATH (requires sudo)\nsudo mv vfm /usr/local/bin/\n\n# Test\nvfm --help\n```\n\n#### **macOS**\n```bash\n# Intel (x86_64)\nwget https://github.com/glinharesb/vtex-files-manager/releases/download/vVERSION/vtex-files-manager_VERSION_Darwin_x86_64.tar.gz\ntar -xzf vtex-files-manager_VERSION_Darwin_x86_64.tar.gz\n\n# Apple Silicon (M1/M2/M3)\nwget https://github.com/glinharesb/vtex-files-manager/releases/download/vVERSION/vtex-files-manager_VERSION_Darwin_arm64.tar.gz\ntar -xzf vtex-files-manager_VERSION_Darwin_arm64.tar.gz\n\n# Move to PATH\nsudo mv vfm /usr/local/bin/\n\n# Test\nvfm --help\n```\n\n#### **Windows**\n1. Download the appropriate `.zip` file from the [releases page](https://github.com/glinharesb/vtex-files-manager/releases/latest)\n2. Extract the `vfm.exe` file\n3. Move to a directory in your PATH (e.g., `C:\\Program Files\\vfm\\`)\n4. Add the directory to system PATH\n5. Open a new terminal and test: `vfm --help`\n\n### Option 3: Install via Go\n\n```bash\ngo install github.com/glinharesb/vtex-files-manager@latest\n```\n\nThe binary will be installed as `vtex-files-manager` in `$GOPATH/bin`. You can create an alias `vfm` or rename the binary.\n\n### Option 4: Build from Source\n\n```bash\ngit clone https://github.com/glinharesb/vtex-files-manager.git\ncd vtex-files-manager\n\n# Build vfm\ngo build -o vfm .\n\n# Optional: Move to PATH\nsudo mv vfm /usr/local/bin/\n\n# Test\nvfm --help\n```\n\n## Usage\n\n### Authentication\n\nThe tool automatically uses the VTEX CLI session. Make sure you're logged in:\n\n```bash\nvtex login\n```\n\n### Single File Upload\n\n```bash\nvfm upload \u003cfile\u003e -m \u003cmethod\u003e\n```\n\n**Examples:**\n```bash\n# Upload with CMS FilePicker (short URLs)\nvfm upload image.jpg -m cms\n\n# Upload with GraphQL (official)\nvfm upload logo.png -m graphql\n\n# Skip confirmation prompt\nvfm upload banner.jpg -m cms -y\n```\n\n### Batch Upload\n\n```bash\nvfm batch \u003cdirectory\u003e -m \u003cmethod\u003e [flags]\n```\n\n**Examples:**\n```bash\n# Upload all files in a directory\nvfm batch ./images -m cms\n\n# Recursive upload with 5 concurrent workers\nvfm batch ./assets -m graphql -r -c 5\n\n# Direct batch (no confirmation)\nvfm batch ./photos -m cms -y\n```\n\n### View Upload Logs\n\n```bash\nvfm logs [flags]\n```\n\n**Examples:**\n```bash\n# View last 50 uploads (default)\nvfm logs\n\n# View only last 10\nvfm logs --limit 10\n\n# View only failed uploads\nvfm logs --status failed\n\n# View only CMS uploads\nvfm logs --method cms\n\n# Combine filters\nvfm logs --status success --method graphql --limit 20\n\n# Clear all logs\nvfm logs --clear\n```\n\nThe logs command displays:\n- Upload timestamp\n- File name and size\n- Method used (CMS or GraphQL)\n- Account and workspace\n- Status (success or failure)\n- Generated URL (if success)\n- Error message (if failure)\n- Summary statistics\n\n**Log location:**\n- Linux: `~/.local/state/vtex-files-manager/uploads.jsonl`\n- macOS: `~/Library/Application Support/vtex-files-manager/uploads.jsonl`\n- Windows: `%LOCALAPPDATA%\\vtex-files-manager\\uploads.jsonl`\n\n## Upload Methods\n\n### CMS FilePicker (`-m cms`)\n- **Advantage**: Short and predictable URLs\n- **URL**: `https://{account}.vtexassets.com/arquivos/filename.ext`\n- **Use**: Upload via CMS admin (legacy)\n- **Verification**: Detects existing files before overwriting\n\n### GraphQL (`-m graphql`)\n- **Advantage**: Official and modern API\n- **URL**: `https://{account}.vtexassets.com/assets/.../uuid___hash.ext`\n- **Use**: Upload via GraphQL mutation\n- **Names**: Automatically generated (UUID + hash)\n\n## Flags\n\n### Upload Command\n\n| Flag | Short | Description | Required |\n|------|-------|-------------|----------|\n| `--method` | `-m` | Upload method (cms or graphql) | ✅ |\n| `--yes` | `-y` | Skip confirmation prompt | ❌ |\n| `--verbose` | `-v` | Verbose output | ❌ |\n\n### Batch Command\n\n| Flag | Short | Description | Default | Required |\n|------|-------|-------------|---------|----------|\n| `--method` | `-m` | Upload method (cms or graphql) | - | ✅ |\n| `--concurrent` | `-c` | Number of concurrent workers | 3 | ❌ |\n| `--recursive` | `-r` | Search in subdirectories | false | ❌ |\n| `--yes` | `-y` | Skip confirmation prompt | false | ❌ |\n| `--verbose` | `-v` | Verbose output | false | ❌ |\n\n### Logs Command\n\n| Flag | Short | Description | Default | Required |\n|------|-------|-------------|---------|----------|\n| `--limit` | `-l` | Maximum entries to display | 50 | ❌ |\n| `--status` | `-s` | Filter by status (success or failed) | - | ❌ |\n| `--method` | `-m` | Filter by method (graphql or cms) | - | ❌ |\n| `--clear` | `-c` | Clear all logs (requires confirmation) | false | ❌ |\n\n## Supported Formats\n\nThe formats below have been validated against the real VTEX API:\n\n| Format | CMS FilePicker | GraphQL | Category | Recommended Use |\n|--------|----------------|---------|----------|-----------------|\n| JPG/JPEG | ✅ | ✅ | Image | Universal |\n| PNG | ✅ | ✅ | Image | Universal |\n| GIF | ✅ | ✅ | Image | Universal |\n| SVG | ✅ | ✅ | Image | Universal |\n| WEBP | ✅ | ✅ | Image | Universal |\n| BMP | ✅ | ❌ | Image | CMS only |\n| PDF | ✅ | ❌ | Document | CMS only |\n| TXT | ✅ | ❌ | Document | CMS only |\n| JSON | ✅ | ❌ | Document | CMS only |\n| XML | ✅ | ❌ | Document | CMS only |\n| CSS | ✅ | ❌ | Web | CMS only |\n| JS | ✅ | ❌ | Web | CMS only |\n\n**Notes:**\n- ✅ = Format accepted by API\n- ❌ = Format rejected by API (returns \"Invalid file format\")\n- **Universal**: Works with both methods (CMS and GraphQL)\n- **CMS only**: Works only with CMS FilePicker method\n- **Limit**: 5MB per file (all formats)\n\n## Advanced Examples\n\n### Upload with Existing File Confirmation\n\n```bash\n$ vfm upload image.jpg -m cms\n\n=== VTEX File Upload ===\nAccount:       myaccount\nWorkspace:     master\nUser:          user@example.com\nMethod:        cms\nFile:          image.jpg (245 KB)\nDestination:   https://myaccount.vtexassets.com/arquivos/image.jpg\n\n⚠️  WARNING: File already exists and will be OVERWRITTEN!\n\nFile exists. Overwrite? [y/N]:\n```\n\n### Batch with Multiple File Verification\n\n```bash\n$ vfm batch ./images -m cms\n\n=== VTEX Batch Upload ===\nAccount:       myaccount\nFiles found:   10 (5.2 MB total)\n\n⚠️  WARNING: 3 file(s) already exist and will be OVERWRITTEN:\n  • logo.png\n  • banner.jpg\n  • icon.svg\n\n3 file(s) will be overwritten. Continue? [y/N]:\n```\n\n### Files with Spaces and Special Characters\n\nThe tool automatically handles URL encoding:\n\n```bash\n$ vfm upload \"my file \u0026 photo.jpg\" -m cms -y\n\n✓ Upload successful!\nFile URL: https://myaccount.vtexassets.com/arquivos/my%20file%20\u0026%20photo.jpg\n```\n\n## Project Structure\n\n```\nvtex-files-manager/\n├── cmd/                    # CLI commands\n│   ├── root.go            # Root command\n│   ├── upload.go          # Single upload command\n│   ├── batch.go           # Batch upload command\n│   ├── logs.go            # Log viewing command\n│   └── helpers.go         # Shared helper functions\n├── pkg/\n│   ├── auth/              # Authentication\n│   │   └── auth.go\n│   ├── client/            # Upload clients\n│   │   ├── common.go      # Shared code\n│   │   ├── filepicker.go  # CMS FilePicker client\n│   │   └── graphql.go     # GraphQL client\n│   ├── logger/            # Logging system\n│   │   └── upload_logger.go\n│   └── vtexcli/           # VTEX CLI integration\n│       └── session.go\n└── main.go\n```\n\n## Troubleshooting\n\n### Error: \"No VTEX session found\"\n\n**Solution**: Run `vtex login` to authenticate.\n\n### Error: \"Failed to get requestToken\"\n\n**Solution**: Make sure your session hasn't expired. Run `vtex login` again.\n\n### Slow Upload\n\n**Solution**: For batch uploads, increase the number of workers with `-c`:\n```bash\nvfm batch ./images -m graphql -c 10\n```\n\n## Development\n\n### Environment Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/glinharesb/vtex-files-manager.git\ncd vtex-files-manager\n\n# Download dependencies\ngo mod download\n\n# Run tests\ngo test ./...\n\n# Build vfm\ngo build -o vfm .\n\n# Run\n./vfm --help\n```\n\n### Code Structure\n\n```\nvtex-files-manager/\n├── .github/\n│   └── workflows/        # CI/CD workflows\n├── cmd/                  # CLI commands (vfm)\n│   ├── root.go          # Root command\n│   ├── upload.go        # Single upload\n│   ├── batch.go         # Batch upload\n│   ├── logs.go          # Log viewing\n│   └── helpers.go       # Helper functions\n├── pkg/\n│   ├── auth/            # Authentication\n│   ├── client/          # Upload clients\n│   │   ├── common.go    # Shared code\n│   │   ├── filepicker.go # CMS FilePicker\n│   │   └── graphql.go   # GraphQL API\n│   ├── logger/          # Logging system\n│   └── vtexcli/         # VTEX CLI integration\n├── scripts/\n│   └── release.sh       # Release script\n├── .goreleaser.yml      # GoReleaser configuration\n└── main.go\n```\n\n### Running Tests\n\n```bash\n# All tests\ngo test ./...\n\n# With verbose output\ngo test -v ./...\n\n# With coverage\ngo test -cover ./...\n\n# Detailed coverage\ngo test -coverprofile=coverage.out ./...\ngo tool cover -html=coverage.out\n```\n\n### Creating a Release\n\n```bash\n# Use the automated script\n./scripts/release.sh v1.2.3\n\n# Or manually (see RELEASE.md)\ngit tag -a v1.2.3 -m \"Release v1.2.3\"\ngit push origin v1.2.3\n```\n\nSee [RELEASE.md](RELEASE.md) for detailed instructions.\n\n## Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a branch for your feature (`git checkout -b feature/MyFeature`)\n3. Commit your changes (`git commit -m 'Add: My feature'`)\n4. Add tests if applicable\n5. Make sure tests pass (`go test ./...`)\n6. Push to the branch (`git push origin feature/MyFeature`)\n7. Open a Pull Request\n\n### Commit Conventions\n\nWe follow [Conventional Commits](https://www.conventionalcommits.org/):\n\n- `feat:` New feature\n- `fix:` Bug fix\n- `docs:` Documentation\n- `test:` Tests\n- `refactor:` Refactoring\n- `style:` Formatting\n- `chore:` Maintenance\n\n**Examples:**\n```bash\ngit commit -m \"feat: add AVIF format support\"\ngit commit -m \"fix: fix timeout on large uploads\"\ngit commit -m \"docs: update README with new examples\"\n```\n\n## Updating\n\n### npm\n```bash\nnpm update -g vtex-files-manager\n```\n\n### Direct download\n```bash\nvfm update\n```\n\n## License\n\nMIT License - see LICENSE for details.\n\n## Author\n\nGabriel Linhares Bernardes\n\n## Links\n\n- [VTEX Documentation](https://developers.vtex.com/)\n- [VTEX CLI](https://github.com/vtex/toolbelt)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglinharesb%2Fvtex-files-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fglinharesb%2Fvtex-files-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglinharesb%2Fvtex-files-manager/lists"}