Skip to content

Remote Collections

The dorsal collection command group allows you to manage your remote collections on DorsalHub.

Collections are groups of file records, typically created using the dorsal dir push --create-collection command.

The command in this group let you list, view, update, and manage the contents and visibility of those collections.

This guide covers the nine sub-commands:

  1. list: List all your collections.
  2. show: Show metadata and files for a single collection.
  3. update: Change a collection's name or description.
  4. add-files: Add one or more files to a collection by hash.
  5. remove-files: Remove one or more files from a collection by hash.
  6. make-public: Make a private collection public.
  7. make-private: Make a public collection private.
  8. export: Export all file records from a collection, and save to your computer.
  9. delete: Permanently delete a collection.

dorsal collection list

This command lists all your available collections on DorsalHub.

Example

  1. First, make sure you have some collections to list

    If you haven't already, create a collection using the dorsal dir push command with the --create-collection argument.

    dorsal dir push /path/to/some/files --create-collection

    Free users are can have up to five collections.

    You can see your remaining collection limit on your DorsalHub Dashboard

  2. Run dorsal collection list to see display collections by their ID:

dorsal collection list

The ID field is unique to that collection, and is how we will view or manage it later:

🔎 Fetching collections from DorsalHub (page 1)...
                                               DorsalHub Collections
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓
┃ ID                               ┃ Name                        ┃ Files ┃ Total Size ┃ Access  ┃    Last Modified ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━┩
│ bqsQjurVM57nFe9HF0E9Kap6pmEAQzO1 │ Quarterly Reports 2009-2018 │    48 │    126 MiB │ Private │ 2025-12-01 14:03 │
│ aBtR0dY4lfKZu2hwd3FzHByCvpVybrZw │ Quarterly Reports 2019-2024 │    21 │     26 MiB │ Private │ 2025-11-21 12:21 │
│ aBtR0dY4lfKZu2hwd3FzHByCvpVybrZw │ Stuff                       │     5 │     26 MiB │ Private │ 2025-11-21 12:21 │
│ KtEJ8hKekwEH7F0FJyhARznKdVFOO2Lf │ Game Files                  │     8 │    343 GiB │ Public  │ 2025-10-31 20:59 │
└──────────────────────────────────┴─────────────────────────────┴───────┴────────────┴─────────┴──────────────────┘

Options

  • Fetch a specific page of results with -p or --page:

    dorsal collection list -p 2

  • Change the number of results per page with --per-page:

    dorsal collection list --per-page 50

  • Get the raw JSON response:

    dorsal collection list --json

CLI Docs

 Usage: dorsal collection list [OPTIONS]                                       

 Lists all available collections on DorsalHub.                                

╭─ Options ─────────────────────────────────────────────────────────────────────╮
│ --page      -p      INTEGER  The page number to retrieve. [default: 1]        │
│ --per-page          INTEGER  The number of collections to retrieve per page.  │
│                              [default: 25]                                    │
│ --json                       Output the full collection list as a raw JSON    │
│                              object.                                          │
│ --help                       Show this message and exit.                      │
╰───────────────────────────────────────────────────────────────────────────────╯

dorsal collection show

This command shows the detailed metadata and the list of files for a single collection.

Example

Run dorsal collection show with a Collection ID.

dorsal collection show zrTz4OKeG9onWMzIqn7RRY9jJvh6KZQ3

This will display information about the collection, as well as a paginated list of the files it contains:

🔎 Fetching collection 'LdHMycfITeldtV63TjOJ73OEoHuybnRz'...
╭─────────────── Collection Metadata ───────────────╮
│ ID:              LdHMycfITeldtV63TjOJ73OEoHuybnRz │
│ Name:            stuff                            │
│ File Count:      5                                │
│ Total Size:      74 MiB                           │
│ Access:          Private                          │
│ Modified:        2025-10-31 21:26:55              │
╰───────────────────────────────────────────────────╯
                                                         Files in Collection
┏━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Name                   ┃    Size ┃ Media Type                  ┃ SHA256 Hash                                                      ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ DorsalHub.pptx         │  40 KiB │ application/vnd.openxmlfor… │ 044607cc132a465221f4d2c6f118657d1f34fabe4c51255878391ac61e5f8893 │
│ Game Files.7z          │  53 MiB │ application/x-7z-compressed │ 128ad69952157b9c6bd85f638aa0959981ae67ce3f5875f12ede1fc50c5700a6 │
│ Things fall apart.epub │ 171 KiB │ application/epub+zip        │ 137cb58b6e9afd606fd3b0a953aeba6caf0b0f1dc3998e1b889216faa26c037b │
│ desktop-latest.msi     │  21 MiB │ application/x-msi           │ 1ef549693f5498c0a06ad54569e5ad7faf914c7e45301a26be62acd11cb57844 │
│ bill.pdf               │  80 KiB │ application/pdf             │ 46b065c86856297dec7ec0004127a5cdebeeff668f99ea7a8169609cbc4a0da5 │
└────────────────────────┴─────────┴─────────────────────────────┴──────────────────────────────────────────────────────────────────┘

Options

  • Display the collection info only (not the file list).

    dorsal collection show <id> --meta-only

  • Step through the file list with --page and --per-page:

    dorsal collection show <id> --page 2 --per-page 100

  • Get the collection, including file records, as a JSON:

    dorsal collection show <id> --json

CLI Docs

 Usage: dorsal collection show [OPTIONS] COLLECTION_ID                         

 Shows metadata and file contents for a single collection.                    

 Note: the order of records will always be by date added.                     

╭─ Arguments ───────────────────────────────────────────────────────────────────╮
│ * collection_id      TEXT  The unique ID of the collection to show.           │
│                            [required]                                         │
╰───────────────────────────────────────────────────────────────────────────────╯
╭─ Options ─────────────────────────────────────────────────────────────────────╮
│ --meta-only              Only display the collection's high-level metadata.   │
│ --page      -p  INTEGER  The page number for the file list. [default: 1]      │
│ --per-page      INTEGER  The number of files to retrieve per page.            │
│                          [default: 30]                                        │
│ --json                   Output the full, detailed collection data as a raw   │
│                          JSON object.                                         │
│ --help                   Show this message and exit.                          │
╰───────────────────────────────────────────────────────────────────────────────╯

dorsal collection update

This command updates the name or description of a remote collection.

Example

Run dorsal collection update with the the collection ID and the fields you want to change as.

Fields you can modify:

  • Name via --name or -n
  • Description via --description or -d
dorsal collection update LdHMycfITeldtV63TjOJ73OEoHuybnRz -n "My Project (Renamed)" -d "A new description."

On success, you'll see a confirmation:

Updating collection 'LdHMycfITeldtV63TjOJ73OEoHuybnRz'...
╭────────────── Update Complete ───────────────────────────╮
│ Collection 'My Project (Renamed)' updated  successfully. │
╰──────────────────────────────────────────────────────────╯

Options

  • Update only the name:

    dorsal collection update <id> --name "New Project Name"

  • Update only the description:

    dorsal collection update <id> --description "A better description."

  • Get the raw JSON response of the updated collection:

    dorsal collection update <id> --name "New Name" --json

CLI Docs

 Usage: dorsal collection update [OPTIONS] COLLECTION_ID                       

 Update the name or description of a remote collection.                       

╭─ Arguments ─────────────────────────────────────────────────────────────────╮
│ * collection_id      TEXT  The unique ID of the collection to update.       │
│                            [required]                                       │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────╮
│ --name         -n      TEXT  A new name for the collection.                 │
│ --description  -d      TEXT  A new description for the collection.          │
│ --json                       Output the updated collection as a raw JSON    │
│                              object.                                        │
│ --help                       Show this message and exit.                    │
╰─────────────────────────────────────────────────────────────────────────────╯

dorsal collection add-files

This command adds one or more files to a remote collection by their hash.

Example

Run dorsal collection add-files with the collection ID and the file hashes you wish to add.

You can provide one or more hashes via the --hash or -h arguments:

dorsal collection add-files <collection-id> -h <hash1> -h <hash2>

Output:

╭─────── Update Complete ────╮
│ Operation complete.        │
│ Added: 1                   │
│ Duplicates ignored: 0      │
╰────────────────────────────╯

File Record Privacy and Collections

Public collections can only accept public file records.

If there is no public* record for a hash, then it cannot be added to a public** collection.

There are no such restrictions on private collections.

Options

  • Read a list of hashes (one per line) from standard input using --from-stdin:

    cat my_hashes.txt | dorsal collection add-files <id> --from-stdin

  • Get the raw JSON API response:

    dorsal collection add-files <id> -h <hash1> --json

CLI Docs

 Usage: dorsal collection add-files [OPTIONS] COLLECTION_ID                    

 Add one or more files to a remote collection by their hash.                  

 You can provide hashes in multiple ways:                                     
 - Using multiple --hash options: --hash <hash1> --hash <hash2>               
 - Piping from another command: cat my_hashes.txt | dorsal collection         
   add-files <id> --from-stdin                                                  

╭─ Arguments ─────────────────────────────────────────────────────────────────╮
│ * collection_id      TEXT  The ID of the collection to add files to.        │
│                            [required]                                       │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────╮
│ --hash      -h      TEXT     A file hash to add. This option can be used    │
│                              multiple times. [default: None]                │
│ --from-stdin                 Read a list of hashes from standard input (one │
│                              hash per line).                                │
│ --json                       Output the results as a raw JSON object.       │
│ --help                       Show this message and exit.                    │
╰─────────────────────────────────────────────────────────────────────────────╯

dorsal collection remove-files

This command removes one or more files from a remote collection by their hash.

Example

Run dorsal collection remove-files with the collection ID and the file hashes you wish to remove.

You can provide one or more hashes via the --hash or -h arguments:

dorsal collection remove-files <id> --hash <hash_to_remove>

Output:

╭─────── Update Complete ────╮
│ Operation complete.        │
│ Removed: 1                 │
│ Not Found (Ignored): 0     │
╰────────────────────────────╯

CLI Docs

 Usage: dorsal collection remove-files [OPTIONS] COLLECTION_ID                 

 Remove one or more files from a remote collection by their hash.             

╭─ Arguments ─────────────────────────────────────────────────────────────────╮
│ * collection_id      TEXT  The ID of the collection to remove files from.   │
│                            [required]                                       │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────╮
│ --hash      -h      TEXT     A file hash to remove. This option can be used │
│                              multiple times. [default: None]                │
│ --from-stdin                 Read a list of hashes from standard input (one │
│                              hash per line).                                │
│ --json                       Output the results as a raw JSON object.       │
│ --help                       Show this message and exit.                    │
╰─────────────────────────────────────────────────────────────────────────────╯

dorsal collection make-public

This command makes a collection public.

This command will fail if the collection:

  • Does not belong to you
  • Is already public
  • Any of the the file hashes inside it do not match a public file record.

Public collections can be viewed by anyone.

Example

Run dorsal collection make-public with the ID of the collection you want to update:

dorsal collection make-public zrTz4OKeG9onWMzIqn7RRY9jJvh6KZQ3

Output (response containing the public collection URL):

╭───────────────────────────────────── Update Complete ─────────────────────────────────────╮
│ Collection is now public.                                                                 │
│                                                                                           │
│ URL: http://dorsalhub.com/user/123456/collections/LdHMycfITeldtV63TjOJ73OEoHuybnRz  │
╰───────────────────────────────────────────────────────────────────────────────────────────╯

Options

  • Get the raw JSON response of the updated collection:

    dorsal collection make-public <id> --json

CLI Docs

 Usage: dorsal collection make-public [OPTIONS] COLLECTION_ID                  

 Makes a remote collection public.                                            

╭─ Arguments ─────────────────────────────────────────────────────────────────╮
│ * collection_id      TEXT  The ID of the collection to make public.         │
│                            [required]                                       │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────╮
│ --json      Output the updated collection as a raw JSON object.             │
│ --help      Show this message and exit.                                     │
╰─────────────────────────────────────────────────────────────────────────────╯

dorsal collection make-private

This command makes a collection private.

This command will fail if the collection:

  • Does not belong to you
  • Is already private

Example

Run dorsal collection make-private with the ID of the collection you want to update:

dorsal collection make-private LdHMycfITeldtV63TjOJ73OEoHuybnRz

Output (response containing the private collection URL):

╭─────────────────────────────────── Update Complete ────────────────────────────────────╮
│ Collection is now private.                                                             │
│                                                                                        │
│ URL: http://dorsalhub.com/dashboard/collections/LdHMycfITeldtV63TjOJ73OEoHuybnRz │
╰────────────────────────────────────────────────────────────────────────────────────────╯

Options

  • Get the raw JSON response of the updated collection:

    dorsal collection make-private <id> --json

CLI Docs

 Usage: dorsal collection make-private [OPTIONS] COLLECTION_ID                 

 Makes a remote collection private.                                           

╭─ Arguments ─────────────────────────────────────────────────────────────────╮
│ * collection_id      TEXT  The ID of the collection to make private.        │
│                            [required]                                       │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────╮
│ --json      Output the updated collection as a raw JSON object.             │
│ --help      Show this message and exit.                                     │
╰─────────────────────────────────────────────────────────────────────────────╯

dorsal collection export

This command allows you to download all file records in a collection at once.

The collection is downloaded to your local computer as a .json.gz file.

Example

Run dorsal collection export with the ID of the collection you wish to export:

dorsal collection export LdHMycfITeldtV63TjOJ73OEoHuybnRz

It will show the progress and save the file to the default export directory.

It may take anything from few seconds to a few minutes to complete, depending on the size of the collection.

📦 Starting export of collection 'LdHMycfITeldtV63TjOJ73OEoHuybnRz'.
   Saving to: /home/user/.dorsal/export/LdHMycfITeldtV63TjOJ73OEoHuybnRz-20251031-221020.json.gz
Downloading... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% • 0:00:10

✅ Export complete in 11.98s.

Export Quota

Exports are limited by user account status.

  • Free: 5 exports per day
  • Power User: 50 exports per day
  • Business: 250 exports per day

Options

  • Specify a custom output directory with -o or --output-dir:

    dorsal collection export <id> -o /path/to/my-exports

  • Get a JSON summary of the export operation instead of the progress bar:

    dorsal collection export <id> --json

CLI Docs

 Usage: dorsal collection export [OPTIONS] COLLECTION_ID                       

 Export all file records from a remote collection to a local file.            

╭─ Arguments ─────────────────────────────────────────────────────────────────╮
│ * collection_id      TEXT  The unique ID of the collection to export.       │
│                            [required]                                       │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────╮
│ --output-dir  -o      PATH   Directory to save the export file. Defaults to │
│                            ~/.dorsal/exports/<collection_id>/               │
│ --json                       Output a JSON summary of the export operation. │
│ --help                       Show this message and exit.                    │
╰─────────────────────────────────────────────────────────────────────────────╯

dorsal collection delete

This command deletes a collection from DorsalHub.

This command only deletes the collection itself. It does not delete the file records it contains.

Example

Run dorsal collection delete with ID of the collection you wish to delete:

dorsal collection delete LdHMycfITeldtV63TjOJ73OEoHuybnRz

It will ask for confirmation. If you confirm, the collection will be deleted.

Are you sure you want to permanently delete collection 'LdHMycfITeldtV63TjOJ73OEoHuybnRz'? [y/N]: y
🗑️  Deleting collection 'LdHMycfITeldtV63TjOJ73OEoHuybnRz'...

✅ Collection 'LdHMycfITeldtV63TjOJ73OEoHuybnRz' was successfully deleted.

Options

  • Bypass the interactive confirmation prompt with -y or --yes:

    dorsal collection delete <id> -y

  • Get a raw JSON response confirming the deletion:

    dorsal collection delete <id> --json

CLI Docs

 Usage: dorsal collection delete [OPTIONS] COLLECTION_ID                       

 Permanently deletes a collection from DorsalHub.                             

╭─ Arguments ─────────────────────────────────────────────────────────────────╮
│ * collection_id      TEXT  The unique ID of the collection to delete.       │
│                            [required]                                       │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────╮
│ --yes     -y            Bypass the interactive confirmation prompt. Use     │
│                         with caution.                                       │
│ --json                  Output the result as a raw JSON object.             │
│ --help                  Show this message and exit.                         │
╰────────────────────────────────________________─────────────────────────────╯

➡️ Continue to: dorsal cache Guide