CloudApp/Zight Downloader

A powerful Node.js package to download, upload, and manage files on Zight (formerly CloudApp). Use it as a CLI tool or as a programmatic library in your Node.js projects.

Features

• ✨ Dual Mode - Use as CLI tool or import as a library in your projects
• 📂 List Drops - View and browse your files with pagination
• 📊 Export to CSV - Export your entire library metadata to a CSV file
• ⬇️ Flexible Downloads - Download by ID, URL, from a list file, or bulk from your account
• ⬆️ Upload Files - Upload single files or entire directories
• 🗑️ Delete & Trash - Delete files, view trash, restore items, or permanently delete
• 🎬 Video Filtering - Option to download only video files
• 📹 Video Requests - Create, list, edit, and delete video request links
• 📁 Collections - View your collections
• 🔔 Notifications - View and manage notifications
• 🔄 Auto Session Refresh - Sessions auto-refresh when expired
• 🔐 Secure Config - Credentials stored securely in your OS config directory
• ⏱️ Rate Limiting - Built-in delays between requests to avoid being blocked

Installation

Via NPM (Recommended)

npm install -g cloudapp-dl

From Source

git clone https://github.com/EcomGraduates/cloudapp-downloader.git
cd cloudapp-downloader
npm install
npm link  # Makes 'cloudapp-dl' available globally

Using as a Library

You can import and use cloudapp-dl as a programmatic library in your Node.js projects.

Quick Start (ESM)

import { ZightClient } from 'cloudapp-dl';

// Create client with email/password
const client = new ZightClient({
  email: '[email protected]',
  password: 'your-password'
});

// Login
await client.login();

// Use the API
const account = await client.getAccountDetails();
console.log('Logged in as:', account.data.user.attributes.email);

Quick Start (CommonJS)

const { ZightClient } = require('cloudapp-dl');

async function main() {
  const client = new ZightClient({
    email: '[email protected]',
    password: 'your-password'
  });

  await client.login();
  
  const account = await client.getAccountDetails();
  console.log('Logged in as:', account.data.user.attributes.email);
}

main();

Authentication Options

// Option 1: Email/Password (will call login() to authenticate)
const client = new ZightClient({
  email: process.env.ZIGHT_EMAIL,
  password: process.env.ZIGHT_PASSWORD
});
await client.login();

// Option 2: Existing Session ID (skip login if you already have a session)
const client = new ZightClient({
  sessionId: 'your-existing-session-id'
});

Debug Mode

Enable debug logging to see what's happening under the hood:

const client = new ZightClient({
  email: '[email protected]',
  password: 'your-password',
  debug: true  // Enables debug logging
});

Available Methods

Account & Info

// Get account details
const account = await client.getAccountDetails();

// Get organization details
const org = await client.getOrganization();

// Check authentication status
console.log('Authenticated:', client.isAuthenticated);
console.log('Session ID:', client.sessionId);

Files & Items

// List items (paginated)
const items = await client.getItemsFromDashboard({ page: 1, perPage: 24 });

// Get all items
const allItems = await client.getAllItems();

// Get a specific item
const item = await client.getItem('itemId');

// Search items
const results = await client.searchDrops('search query');

// Get drops (files)
const drops = await client.getDrops({ page: 1, perPage: 20 });

Upload & Download

// Upload a file
const result = await client.uploadFile('./screenshot.png');
console.log('Share URL:', result.share_url);

// Upload with progress callback
const result = await client.uploadFile('./video.mp4', (progress) => {
  const percent = Math.round((progress.loaded / progress.total) * 100);
  console.log(`Upload progress: ${percent}%`);
});

// Get download URL for an item
const item = await client.getItem('itemId');
console.log('Download URL:', item.download_url);

Delete & Trash

// Delete an item (move to trash)
await client.deleteItem('itemId');

// Permanently delete an item
await client.deleteItem('itemId', true);

// List items in trash
const trashItems = await client.getTrashItems();

// Restore an item from trash
await client.restoreItem('itemId');

// Empty trash
await client.emptyTrash();

Video Requests

// Create a video request link
const request = await client.createVideoRequest({
  name: 'Help me with this bug',
  message: 'Please record your screen showing the issue'
});
console.log('Share link:', request.data.request_content.links.request_link);

// List all video requests
const requests = await client.getVideoRequests();

// Get a specific request
const req = await client.getVideoRequest('requestId');

// Update a request
await client.updateVideoRequest('requestId', {
  name: 'Updated Title',
  message: 'Updated instructions'
});

// Delete a request
await client.deleteVideoRequest('requestId');

Collections

// List collections
const collections = await client.getCollections();

// Get all collections
const allCollections = await client.getAllCollections();

Notifications

// Get notifications
const notifications = await client.getNotifications({ limit: 10 });

// Get unread notifications
const unread = await client.getNotifications({ viewed: 'no', limit: 20 });

// Mark a notification as read
await client.markNotificationViewed('notificationId');

// Mark all notifications as read
await client.markAllNotificationsViewed();

Full Example

import { ZightClient } from 'cloudapp-dl';

async function main() {
  // Initialize client
  const client = new ZightClient({
    email: process.env.ZIGHT_EMAIL,
    password: process.env.ZIGHT_PASSWORD,
    debug: false
  });

  // Login
  await client.login();
  console.log('Logged in successfully!');

  // Get account info
  const account = await client.getAccountDetails();
  const user = account.data.user;
  console.log(`Welcome, ${user.attributes.name}!`);
  console.log(`You have ${user.attributes.item_count} items.`);

  // Upload a file
  const uploadResult = await client.uploadFile('./screenshot.png');
  console.log('Uploaded:', uploadResult.share_url);

  // Create a video request
  const request = await client.createVideoRequest({
    name: 'Support Request',
    message: 'Please record your screen showing the issue'
  });
  console.log('Request link:', request.data.request_content.links.request_link);

  // List recent items
  const items = await client.getItemsFromDashboard({ page: 1, perPage: 12 });
  console.log(`Recent items: ${items.items.length}`);

  // Get notifications
  const notifications = await client.getNotifications({ limit: 5 });
  console.log(`Notifications: ${notifications.data.client_notifications.length}`);
}

main().catch(console.error);

Demo Scripts

Check out the demo/ directory for example scripts:

cd demo
cp env.example .env
# Edit .env with your credentials

npm install dotenv
node demo.js              # Run all demos
node demo.js upload ./file.png
node demo.js create-request
node demo.js notifications

CLI Usage

Commands Overview

cloudapp-dl login                  Login to your Zight account
cloudapp-dl logout                 Logout and clear session
cloudapp-dl account                Display your Zight account details
cloudapp-dl whoami                 Show current login status
cloudapp-dl config                 View or manage configuration

cloudapp-dl list                   List your drops/files from Zight
cloudapp-dl export                 Export items to CSV file
cloudapp-dl collections            List your collections

cloudapp-dl get <id>               Download a single file by ID
cloudapp-dl download <url>         Download a single file by URL
cloudapp-dl download-list <file>   Download multiple files from a URL list
cloudapp-dl bulk-download          Bulk download files from your account

cloudapp-dl upload <file>          Upload a file to Zight
cloudapp-dl bulk-upload <path>     Upload multiple files from a directory

cloudapp-dl delete <id>            Delete a file (move to trash)
cloudapp-dl trash                  List items in trash
cloudapp-dl restore <id>           Restore a file from trash
cloudapp-dl empty-trash            Permanently delete all trash items

cloudapp-dl request                Create a video request (interactive)
cloudapp-dl request-quick          Instantly create a video request
cloudapp-dl requests               List your video requests
cloudapp-dl request-details <id>   View request details and submitted items
cloudapp-dl request-download <id>  Download all items from a request
cloudapp-dl request-edit <id>      Edit a video request
cloudapp-dl request-delete <id>    Delete a video request

cloudapp-dl help                   Show help information

Account Commands

Login to Your Account

cloudapp-dl login

You'll be prompted for your email and password. Credentials are stored locally for future sessions.

You can also provide credentials directly:

cloudapp-dl login --email [email protected] --password yourpassword

View Account Details

cloudapp-dl account

Displays your account information including name, email, item count, and plan details.

Check Login Status

cloudapp-dl whoami

Quick check of your current login status and session validity.

Logout

cloudapp-dl logout

Clears your session (credentials remain stored for easy re-login).

Configuration

View your current configuration:

cloudapp-dl config

Show config file path:

cloudapp-dl config --path

Clear all configuration data:

cloudapp-dl config --clear

Listing & Exporting

List Your Drops

cloudapp-dl list

Lists your drops/files from Zight. Supports pagination:

cloudapp-dl list --page 2 --per-page 48

List Your Collections

cloudapp-dl collections

Displays all your collections with their IDs, names, item counts, and view counts.

Export to CSV

Export all your items to a CSV file:

cloudapp-dl export

Export specific pages:

cloudapp-dl export --start-page 1 --end-page 10

Export to a specific file:

cloudapp-dl export --out my-export.csv

CSV Columns:

• # - Row number
• ID - Zight file ID
• Title - File name/title
• Type - File extension (.mp4, .png, .zip, etc.)
• Views - View count
• Date - Creation date
• URL - Share URL
• Is Video - Yes/No
• Thumbnail - Thumbnail URL

Downloading Files

Download by ID

Download a file using its Zight ID:

cloudapp-dl get WnuPyJR5

Download to specific directory:

cloudapp-dl get WnuPyJR5 --out ./downloads

Use ID as filename instead of title:

cloudapp-dl get WnuPyJR5 --no-title

Download by URL

Download a file using its full URL:

cloudapp-dl download https://share.zight.com/WnuPyJR5

Download to specific directory:

cloudapp-dl download https://share.zight.com/WnuPyJR5 --out ./downloads

Download from URL List

Create a text file with one URL per line (urls.txt):

https://share.zight.com/ABC123
https://share.zight.com/DEF456
https://share.zight.com/GHI789

Then download all of them:

cloudapp-dl download-list urls.txt

With options:

cloudapp-dl download-list urls.txt --out ./videos --prefix video --timeout 5000

Bulk Download from Account

Download ALL files from your logged-in account:

cloudapp-dl bulk-download

With options:

cloudapp-dl bulk-download --out ./my-files --limit 50 --videos-only

Download specific pages:

cloudapp-dl bulk-download --start-page 1 --end-page 10

Uploading Files

Upload a Single File

cloudapp-dl upload ./video.mp4

cloudapp-dl upload ~/Desktop/screenshot.png

Bulk Upload from Directory

Upload all files in a directory:

cloudapp-dl bulk-upload ./screenshots/

With custom delay between uploads:

cloudapp-dl bulk-upload ./videos/ --timeout 3000

Supported File Types

The uploader automatically detects MIME types:

| Category | Extensions | |----------|------------| | Video | .mp4, .mov, .avi, .webm, .mkv, .m4v | | Images | .png, .jpg, .jpeg, .gif, .webp, .svg, .bmp | | Audio | .mp3, .wav, .ogg, .m4a | | Documents | .pdf, .doc, .docx, .xls, .xlsx, .ppt, .pptx, .txt, .csv | | Archives | .zip, .rar, .7z, .tar, .gz |

Deleting Files & Trash

Delete a File (Move to Trash)

Delete a file by moving it to trash (recoverable for 30 days):

cloudapp-dl delete WnuPyJR5

Skip confirmation:

cloudapp-dl delete WnuPyJR5 --yes

Permanently Delete

Permanently delete a file (no recovery):

cloudapp-dl delete WnuPyJR5 --permanent

⚠️ Warning: Permanent deletion cannot be undone!

View Trash

List all items in your trash:

cloudapp-dl trash

Shows item ID, name, created date, and deleted date.

Restore from Trash

Restore a file from trash:

cloudapp-dl restore WnuPyJR5

Empty Trash

Permanently delete ALL items in trash:

cloudapp-dl empty-trash

Skip confirmation:

cloudapp-dl empty-trash --yes

Video Requests

Create shareable links that allow others to record videos for you. The recordings will automatically appear in your Zight account.

Create Request (Interactive)

cloudapp-dl request

This will guide you through:

1. Title for the request
2. Message/instructions for the recorder
3. Optional custom ID
4. Optional expiration date
5. Optional collection to save recordings to

Create Request (Quick)

Instantly create a request with defaults:

cloudapp-dl request-quick

With options:

cloudapp-dl request-quick -t "Help me debug" --custom-id "TICKET-123"

Create Request (With Options)

cloudapp-dl request \
  --title "Bug Report" \
  --message "Record your screen showing the bug" \
  --custom-id "TICKET-123" \
  --expires "12/31/2025 5:00pm" \
  --collection Y2foRdo

List All Requests

cloudapp-dl requests

Show with full links:

cloudapp-dl requests --verbose

View Request Details & Items

View a request and all items submitted to it:

cloudapp-dl request-details wgsX51

With download URLs:

cloudapp-dl request-details wgsX51 --verbose

Download Items from a Request

Download all videos/files submitted to a request:

cloudapp-dl request-download wgsX51

With options:

cloudapp-dl request-download wgsX51 --out ./submissions --timeout 3000

Edit a Request

cloudapp-dl request-edit ABC123 --title "New Title"

Edit multiple fields:

cloudapp-dl request-edit ABC123 \
  --title "Updated Title" \
  --message "New instructions" \
  --expires "12/31/2025 5:00pm"

Remove expiration:

cloudapp-dl request-edit ABC123 --expires never

Change collection:

cloudapp-dl request-edit ABC123 --collection Y2foRdo

Delete a Request

cloudapp-dl request-delete ABC123

Skip confirmation:

cloudapp-dl request-delete ABC123 --yes

Date Format for Expiration

The expiration date accepts multiple formats:

• 12/31/2025 5:00pm
• 12/31/2025 17:00
• 2025-12-31 5:00pm
• 12/31/2025 (expires at end of day)

Options Reference

Global Options

| Option | Alias | Description | |--------|-------|-------------| | --help | -h | Show help | | --version | -v | Show version |

List Options

| Option | Alias | Description | |--------|-------|-------------| | --page | | Page number (default: 1) | | --per-page | | Items per page - multiples of 12 (default: 12) |

Export Options

| Option | Alias | Description | |--------|-------|-------------| | --out | -o | Output CSV file path | | --start-page | | Start from this page | | --end-page | | End at this page |

Download Options (get, download)

| Option | Alias | Description | |--------|-------|-------------| | --out | -o | Output path/directory | | --no-title | | Use file ID as filename instead of title |

Download List Options

| Option | Alias | Description | |--------|-------|-------------| | --out | -o | Output directory | | --prefix | -p | Filename prefix (e.g., "video" → video-1.mp4) | | --timeout | -t | Delay between downloads in ms (default: 2000) |

Bulk Download Options

| Option | Alias | Description | |--------|-------|-------------| | --out | -o | Output directory (default: ./downloads) | | --start-page | | Start from this page | | --end-page | | End at this page | | --limit | | Maximum number of files to download | | --videos-only | | Only download video files | | --timeout | -t | Delay between downloads in ms (default: 2000) | | --no-title | | Use file IDs as filenames instead of titles |

Upload Options

| Option | Alias | Description | |--------|-------|-------------| | --timeout | -t | Delay between uploads in ms (default: 2000) - bulk-upload only |

Delete Options

| Option | Alias | Description | |--------|-------|-------------| | --permanent | | Permanently delete (no recovery) | | --yes | -y | Skip confirmation prompt |

Empty Trash Options

| Option | Alias | Description | |--------|-------|-------------| | --yes | -y | Skip confirmation prompt |

Request Options (request, request-quick)

| Option | Alias | Description | |--------|-------|-------------| | --title | -t | Title for the request | | --message | -m | Message/instructions for the recorder | | --custom-id | | Custom identifier for tracking | | --expires | -e | Expiration date (e.g., "12/31/2025 5:00pm") | | --collection | -c | Collection ID to save recordings to |

Request Edit Options

| Option | Alias | Description | |--------|-------|-------------| | --title | -t | New title | | --message | -m | New message | | --custom-id | | New custom identifier | | --expires | -e | New expiration date (or "never" to remove) | | --collection | -c | New collection ID (empty to remove) |

Request Delete Options

| Option | Alias | Description | |--------|-------|-------------| | --yes | -y | Skip confirmation prompt |

Request Details Options

| Option | Alias | Description | |--------|-------|-------------| | --verbose | -v | Show download URLs for each item |

Request Download Options

| Option | Alias | Description | |--------|-------|-------------| | --out | -o | Output directory (default: .) | | --timeout | -t | Delay between downloads in ms (default: 2000) |

Requests List Options

| Option | Alias | Description | |--------|-------|-------------| | --verbose | -v | Show full request links |

Config File Location

Your configuration is stored at:

• macOS/Linux: ~/.config/cloudapp-dl/config.json
• Windows: %APPDATA%\cloudapp-dl\config.json

Session Management

The CLI automatically manages your session:

1. On login, your session ID and expiry are stored
2. Before each API request, the session validity is checked
3. If expired, the CLI automatically re-authenticates using stored credentials
4. Each API response updates the session cookie, keeping it fresh

Quick Examples

# Login to your account
cloudapp-dl login

# List your files
cloudapp-dl list --per-page 24

# Export everything to CSV
cloudapp-dl export

# Download a single file by ID
cloudapp-dl get WnuPyJR5

# Download a single file by URL
cloudapp-dl download https://share.zight.com/ABC123

# Download from a list of URLs
cloudapp-dl download-list urls.txt --out ./videos

# Bulk download all videos from your account
cloudapp-dl bulk-download --videos-only --out ./my-videos

# Upload a file
cloudapp-dl upload ./screenshot.png

# Bulk upload a directory
cloudapp-dl bulk-upload ./screenshots/

# Create a video request link
cloudapp-dl request -t "Support" -m "Record your screen showing the issue"

# Create a quick video request
cloudapp-dl request-quick

# List all video requests
cloudapp-dl requests

# View request details and submitted items
cloudapp-dl request-details wgsX51

# Download all items from a request
cloudapp-dl request-download wgsX51 --out ./submissions

# Edit a request
cloudapp-dl request-edit ABC123 --title "New Title" --expires "12/31/2025"

# Delete a request
cloudapp-dl request-delete ABC123 --yes

# Delete a file (move to trash)
cloudapp-dl delete WnuPyJR5

# Permanently delete a file
cloudapp-dl delete WnuPyJR5 --permanent --yes

# View trash
cloudapp-dl trash

# Restore a file from trash
cloudapp-dl restore WnuPyJR5

# Empty trash
cloudapp-dl empty-trash --yes

# List your collections
cloudapp-dl collections

Dependencies

• axios - HTTP client
• cheerio - HTML parsing
• form-data - Multipart form data for uploads
• yargs - CLI argument parsing

Requirements

• Node.js >= 16.0.0

Troubleshooting

Session Expired

If you see session expired errors, simply run cloudapp-dl login again. The CLI will automatically re-authenticate using your stored credentials.

Rate Limiting

If downloads/uploads are failing, try increasing the timeout between requests:

cloudapp-dl bulk-download --timeout 5000  # 5 second delay
cloudapp-dl bulk-upload ./files/ --timeout 5000

File Already Exists

The bulk download and download-list commands automatically skip files that already exist in the output directory.

Upload Failed

Make sure you're logged in and have permission to upload files to your Zight account. Check your account's storage limits.

Contributing

Pull requests are welcome. For major changes, please open an issue first.

License

MIT

Made with ❤️ by ECOMGRADUATES LLC