Skip to content

Remote Records

The dorsal record command group allows you to view, search, and manage the file metadata records on DorsalHub.

This is how you interact with the metadata for your files after they have been pushed using the dorsal file push or dorsal dir push commands.

This guide covers the five sub-commands:

  1. get: Retrieve a single, complete record by its hash.
  2. search: Search all your records.
  3. delete: Delete a record and its associated data from DorsalHub.
  4. tag add: Add tags to a remote record.
  5. tag rm: Delete tags from a remote record.

dorsal record get

This command retrieves a single file record from DorsalHub via its hash (e.g., SHA-256)

Example

  1. Find the hash of a file you indexed earlier, or just use this one:

    3383fb2ab568ca7019834d438f9a14b9d2ccaa2f37f319373848350005779368

  2. Run dorsal record get with the hash:

    dorsal record get 3383fb2ab568ca7019834d438f9a14b9d2ccaa2f37f319373848350005779368

If found, you'll see a panel with the full record from DorsalHub.

🔎 Searching for file record with hash
3383fb2ab568ca7019834d438f9a14b9d2ccaa2f37f319373848350005779368
╭───────────────────────────────── File Record: PDFSPEC.pdf ─────────────────────────────────╮
│                                                                                            │
│    Hashes                                                                                  │
│       SHA-256:  3383fb2ab568ca7019834d438f9a14b9d2ccaa2f37f319373848350005779368           │
│          TLSH:  T13465D67BB4C61D6DF893CA46571C579B8B0D71533BAEA58604BDAF0AC6338029AC3F41   │
│                                                                                            │
│    File Info                                                                               │
│          Name:  PDFSPEC.pdf                                                                │
│          Size:  1 MiB                                                                      │
│    Media Type:  application/pdf                                                            │
│                                                                                            │
│    Tags                                                                                    │
│      language:    English (private) [id: 69035139793ae72b07f05380]                         │
│                                                                                            │
│    Pdf Info                                                                                │
│            author:  Tim Bienz, Richard Cohn, James R. Meehan                               │
│             title:  Portable Document Format Reference Manual (v 1.2)                      │
│           creator:  FrameMaker 5.1.1                                                       │
│          producer:  Acrobat Distiller 3.0 for Power Macintosh                              │
│           subject:  Description of the PDF file format                                     │
│          keywords:  Acrobat PDF                                                            │
│           version:  1.2                                                                    │
│        page_count:  394                                                                    │
│     creation_date:  1996-11-12T03:08:43Z                                                   │
│     modified_date:  1996-11-12T07:58:15Z                                                   │
│                                                                                            │
│                                                                                            │
╰────────────────────────────────────────────────────────────────────────────────────────────╯

dorsal file scan vs dorsal record get

The output from these two commands looks almost identical, but there are some differences:

  1. User-contributed tags and annotations are retrieved when you run dorsal record get (note the language tag in the example). This includes public tags and annotations contributed by other users who have indexed the same file.

  2. Some fields, such as the local file path and date modified are present when you run dorsal file scan but not when you run dorsal record get. This is because these fields are not stored on DorsalHub, as they are are typically system-specific.

Options

  • Search only your privately indexed records:

    dorsal record get <hash> --private

  • Search only public records:

    dorsal record get <hash> --public

  • Output the full, raw JSON to your terminal with --json:

    dorsal record get <hash> --json

  • Save the full JSON record to a file with -s or --save:

    dorsal record get <hash> -s

  • Specify a custom output file path for the JSON report:

    dorsal record get <hash> -o "my-record.json"

CLI Docs

 Usage: dorsal record get [OPTIONS] HASH_STRING                                

 Get a single file record from DorsalHub by its hash.                         
 By default, searches for records you have access to (both public and         
 private).                                                                    

╭─ Arguments ─────────────────────────────────────────────────────────────────╮
│ * hash_string      TEXT  The hash (e.g., SHA256) of the file to find.       │
│                          [required]                                         │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                 │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Search Options ────────────────────────────────────────────────────────────╮
│ --private             Restrict search to only your private file records.    │
│ --public              Restrict search to only public file records.          │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Output Options ────────────────────────────────────────────────────────────╮
│ --json                  Output the full metadata as a raw JSON object.      │
│ --save    -s            Save the JSON record to the default directory or    │
│                         --output path.                                      │
│ --output  -o      PATH  Path to save the output JSON file.                  │
╰─────────────────────────────────────────────────────────────────────────────╯

Alias: dorsal search

This command searches across all records you have indexed to DorsalHub (either public or private).

You can also search all public records indexed by other users on the platform, as a premium feature.

Example

  1. Run dorsal record search with a query string:

    dorsal record search "pdf data science"

    You can also use the shorter dorsal search alias:

    dorsal search "pdf data science"

    By default this search is limited to files you have indexed.

  2. To search across all files indexed publicly across DorsalHub pass -g or --global (requires a premium subscription):

    dorsal record search "pdf data science" --global
    You can also use use the shorter dorsal search alias:

    dorsal search "pdf data science" --global

  3. When a search is complete it will display a paginated table of results:

    🔎 Searching user scope for records matching: 'pdf data science'
                                                    User Search Results
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Name                        ┃    Size ┃ Media Type      ┃ SHA256 Hash                                                        ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ 2015 Gopi Subramanian -     │         │                 │                                                                    │
│ Python Data Science         │   4 MiB │ application/pdf │ e23a2a882d8c11c200d7a1c547d2114e8968cc4ad0952c5f882cf7a24dab79d2   │
│ Cookbook_Rsll.pdf           │         │                 │                                                                    │
│ 2017 Thomas Mailund -       │         │                 │                                                                    │
│ Beginning Data Science in   │   6 MiB │ application/pdf │ 8ff5d5f21ffa76b7ac9cd91d46a9c881cf4ab9b84582cb93f779a034a4200306   │
│ R.pdf                       │         │                 │                                                                    │
│ Data Science from Scratch - │   5 MiB │ application/pdf │ 403d83d625362987cc0d9a45db4a55e282f3cc7c1f52e4dfdcdb18c48a3b7e28   │
│ Joel Grus.pdf               │         │                 │                                                                    │
│ data_science-booklet-16-17… │ 956 KiB │ application/pdf │ 93ed9a7b53c44116cbecf607f5bfd39c2a6cbef1e158d7fcbd6865d47819aa9f   │
│ Python Data Science         │         │                 │                                                                    │
│ Handbook - Jake             │  20 MiB │ application/pdf │ a1697546c691e0d29ce01fa5b34d41daa96fe0cd9f1138239258a6f6f7d2b39d   │
│ VanderPlas.pdf              │         │                 │                                                                    │
│ R for Data Science - Hadley │         │                 │                                                                    │
│ Wickham, Garrett            │  32 MiB │ application/pdf │ 70c480a8ae6e148e04e3bb04dee343f48cf86e1b9179430e8da30577e3b76be5   │
│ Grolemu.pdf                 │         │                 │                                                                    │
└─────────────────────────────┴─────────┴─────────────────┴────────────────────────────────────────────────────────────────────┘
Search powered by DorsalHub Search 0.1 beta. For search syntax, visit: https://docs.dorsalhub.com/search
Showing page 1 of 1 | Displaying records 1 - 6 of 6 total.

Options

  • Perform a global search across all public files (Premium feature) with --global or -g:

    dorsal record search "cve-2025" -g

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

    dorsal record search "report" -p 2

  • Change the number of results per page:

    dorsal record search "report" --per-page 50

  • Sort results by a different field (e.g., size):

    dorsal record search "media" --sort-by size --sort-order asc

  • Output the full, raw JSON results to your terminal with --json:

    dorsal record search "pdf" --json

  • Save the JSON results to a file with -s or --save:

    dorsal record search "pdf" -s

CLI Docs

 Usage: dorsal record search [OPTIONS] QUERY                                   

 Search DorsalHub file records.                                               

╭─ Arguments ─────────────────────────────────────────────────────────────────╮
│ * query       TEXT  The search query string. Queries with spaces must be    │
│                     enclosed in quotes. [required]                          │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                 │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Search Options ────────────────────────────────────────────────────────────╮
│ --global   -g         Perform a global search across all public files       │
│                       (Premium).                                            │
│ --page     -p  INTEGER  The page number of results to display. [default: 1] │
│ --per-page   INTEGER  The number of results to display per page.            │
│                       [default: 30]                                         │
│ --sort-by    TEXT     Field to sort results by. [default: date_modified]    │
│ --sort-order TEXT     Sort order ('asc' or 'desc'). [default: desc]         │
│ --or                  Use OR logic for the query. By default, multiple      │
│                       terms are combined with AND.                          │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Output Options ────────────────────────────────────────────────────────────╮
│ --json                Output results as a raw JSON object.                  │
│ --save     -s         Save the JSON search results to the default           │
│                       directory or --output path.                           │
│ --output   -o    PATH   Custom path to save the JSON search results (e.g.,  │
│                       'results.json').                                      │
╰─────────────────────────────────────────────────────────────────────────────╯

dorsal record delete

Use this command to delete a file record by its hash. This command will also delete any tags or annotations you added to the file record.

You can pass arguments to only delete the record itself, or only the tags or annotations, but by default it deletes everything.

Example

  1. Run dorsal record delete on a file hash. It will first show you what will be deleted and ask for confirmation.

    dorsal record delete 3383fb2ab568ca7019834d438f9a14b9d2ccaa2f37f319373848350005779368

    🔎 Finding record to delete...
╭───────────────────────────────── File Record: PDFSPEC.pdf ─────────────────────────────────╮
│                                                                                            │
│    Hashes                                                                                  │
│       SHA-256:  3383fb2ab568ca7019834d438f9a14b9d2ccaa2f37f319373848350005779368           │
│          TLSH:  T13465D67BB4C61D6DF893CA46571C579B8B0D71533BAEA58604BDAF0AC6338029AC3F41   │
│                                                                                            │
│    File Info                                                                               │
│          Name:  PDFSPEC.pdf                                                                │
│          Size:  1 MiB                                                                      │
│    Media Type:  application/pdf                                                            │
│                                                                                            │
│    Tags                                                                                    │
│      language:    English (private) [id: 69035139793ae72b07f05380]                         │
│                                                                                            │
│    Pdf Info                                                                                │
│            author:  Tim Bienz, Richard Cohn, James R. Meehan                               │
│             title:  Portable Document Format Reference Manual (v 1.2)                      │
│           creator:  FrameMaker 5.1.1                                                       │
│          producer:  Acrobat Distiller 3.0 for Power Macintosh                              │
│           subject:  Description of the PDF file format                                     │
│          keywords:  Acrobat PDF                                                            │
│           version:  1.2                                                                    │
│        page_count:  394                                                                    │
│     creation_date:  1996-11-12T03:08:43Z                                                   │
│     modified_date:  1996-11-12T07:58:15Z                                                   │
│                                                                                            │
│                                                                                            │
╰────────────────────────────────────────────────────────────────────────────────────────────╯
╭───────────────────────────────────────── Action Summary ──────────────────────────────────────────╮
│                                                                                                   │
│  For the hash 3383fb2ab568ca7019834d438f9a14b9d2ccaa2f37f319373848350005779368... this operation  │
│  will:                                                                                            │
│  - Delete both public and private records                                                         │
│  - Delete your public and private tags                                                            │
│  - Delete your public and private annotations                                                     │
│                                                                                                   │
╰───────────────────────────────────────────────────────────────────────────────────────────────────╯
Are you sure you want to perform this deletion operation?  [y/N]:

  2. If you confirm, the record will be deleted from DorsalHub:

    🗑️ Deleting record 3383fb2ab568ca7019834d438f9a14b9d2ccaa2f37f319373848350005779368
╭────────── Deletion Complete ──────────╮
│ 1 record(s) permanently deleted.      │
│                                       │
│ Removed 1 tag(s) and 1 annotation(s). │
╰───────────────────────────────────────╯

Options

  • Delete only the private record, leaving the public one (if it exists):

    dorsal record delete <hash> --record private

  • Delete only the public record, leaving the private one (if it exists):

    dorsal record delete <hash> --record private

  • Delete only your public tags, leaving your private tags and all records:

    dorsal record delete <hash> --record none --tags public --annotations none

  • Skip the interactive confirmation prompt:

    dorsal record delete <hash> -y

  • Output the raw JSON API response:

    dorsal record delete <hash> --json

CLI Docs

 Usage: dorsal record delete [OPTIONS] HASH_STRING                              

 Deletes a file record and/or its associated data from DorsalHub with         
 granular control.                                                            

 The default behavior is a "full clean", targeting all records, tags, and     
 annotations associated with the user for the given hash.                     

╭─ Arguments ─────────────────────────────────────────────────────────────────╮
│ * hash_string      TEXT  The hash of the file record to delete. [required]  │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────╮
│ --record      [all|public|private|none]                                     │
│                       Specify which core file record(s) to delete.          │
│                       [default: all]                                        │
│ --tags        [all|public|private|none]                                     │
│                       Specify which of the user's tags to delete for this   │
│                       hash. [default: all]                                  │
│ --annotations [all|public|private|none]                                     │
│                       Specify which of the user's annotations to delete     │
│                       for this hash. [default: all]                         │
│ --yes     -y            Bypass the interactive confirmation prompt. Use     │
│                       with caution.                                         │
│ --json                  Output result as a raw JSON object.                 │
│ --help                  Show this message and exit.                         │
╰─────────────────────────────────────────────────────────────────────────────╯

dorsal record tag add

This command adds a new tag to a file record on DorsalHub.

As with other commands for adding metadata, tags are created as private by default.

You can add tags in two ways:

  1. Labels Tags: Add a private label to a file record (e.g., "urgent", "complete"). These are tags in the label namespace and are always private.
  2. Key-Value Tags: The tag's name and its value, e.g. "language:eng" or "corrupted:true".

Private vs. Public Tags

  • Private tags are free-form, meaning you can provide any name and value you like (e.g., my_project:alpha, q3status:in-progress).
  • Public tags are more restricted. There are a limited number of possible public tags (e.g. language).

To learn more about the tag system, including what public tags are allowed, see: Tagging Guide

Example

  1. Add a private tag genre:Sci-Fi to a file record:

    The private genre tag is a freeform field, meaning you can provide any value for it.

    "genre" is the name of the tag we are adding, which "Sci-Fi" is its value.

    dorsal record tag add c77c02b50c88d1ec8e07abadb18d104de5146e3eb7b434a67985e99ba84badb3 -n "genre" -v "Sci-Fi"

    ✏️  Adding private tag to file c77c02b50c88d1ec8e07abadb18d104de5146e3eb7b434a67985e99ba84badb3...
✅ Successfully added tag 'genre:Sci-Fi'.

  2. Add a private label tag to-read to a File Record:

    You can label any document with a short word or phrase (like "to-read", "urgent", or "review"). This automatically creates a private tag with the name label and your value.

    dorsal record tag add c77c02b50c88d1ec8e07abadb18d104de5146e3eb7b434a67985e99ba84badb3 "urgent"

    ✏️  Adding private tag 'urgent' (label) to file c77c02b5...
✅ Successfully added tag 'label:urgent'.

    Note: this is equivalent to running:

    dorsal record tag add c77c02b50c88d1ec8e07abadb18d104de5146e3eb7b434a67985e99ba84badb3 --name="label" --value="urgent"

  3. You can confirm the tag exists by retrieving the record again

    dorsal record get c77c02b50c88d1ec8e07abadb18d104de5146e3eb7b434a67985e99ba84badb3

    You will see the record in the terminal, with the tag you just added:

    🔎 Searching for file record with hash c77c02b50c88d1ec8e07abadb18d104de5146e3eb7b434a67985e99ba84badb3
╭────────────────────── File Record: Snow Crash - Neal Stephenson.epub ──────────────────────╮
│                                                                                            │
│   Hashes                                                                                   │
│       SHA-256:  c77c02b50c88d1ec8e07abadb18d104de5146e3eb7b434a67985e99ba84badb3           │
│          TLSH:  T135F422335C5D4B84C60F2EB9250778585A7C83D9EA10D80BAFB3D6A524F16F1172F3AA   │
│                                                                                            │
│   File Info                                                                                │
│          Name:  Snow Crash - Neal Stephenson.epub                                          │
│          Size:  757 KiB                                                                    │
│    Media Type:  application/epub+zip                                                       │
│                                                                                            │
│   Tags                                                                                     │
│       genre:    Sci-Fi (private) [id: 6903b66b3dd03157960df671]                            │
│       label:    to-read (private) [id: 6903b66b3dd03157960df672]                           │
│                                                                                            │
│   Ebook Info                                                                               │
│                 title:  Snow Crash                                                         │
│               authors:  Neal Stephenson                                                    │
│             publisher:  Random House Publishing Group                                      │
│              language:  eng                                                                │
│                rights:  Copyright 1992                                                     │
│                  isbn:  9780553898194                                                      │
│            cover_path:  OEBPS/images/Step_9780553898194_epub_cvi_r1.jpg                    │
│      publication_date:  2003-08-26T00:00:00Z                                               │
│                                                                                            │
│                                                                                            │
╰────────────────────────────────────────────────────────────────────────────────────────────╯

Options

  • Add a public tag (public tags visible to anyone who can view the file record):

    dorsal record tag add <hash> -n <tag> -v <value> --public

  • Output the raw JSON for the API response:

    dorsal record tag add <hash> -n <tag> -v <value> --json

CLI Docs

 Usage: dorsal record tag add [OPTIONS] HASH_STRING [LABEL]

 Adds a public or private tag to a file record on DorsalHub.

 You can add tags in two ways:

 1. Simple Label (Private Only):
    dorsal tag add <hash> urgent -> Creates 'label:urgent'

 2. Key-Value Pair (Private or Public):
    dorsal tag add <hash> --name genre --value sci-fi                 

╭─ Arguments ─────────────────────────────────────────────────────────────────╮
│ * hash_string      TEXT  The hash of the file to tag. [required]            │
│   label            TEXT  A simple private label (e.g. 'urgent'). Maps to    │
│                          'label:urgent'. [default: None]                    │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────╮
│ --name    -n      TEXT  The name of the tag (e.g. 'genre').                 │
│ --value   -v      TEXT  The value for the tag (e.g. 'SciFi').               │
│ --public                Create a public tag.                                │
│ --json                  Output result as a raw JSON object.                 │
│ --help                  Show this message and exit.                         │
╰─────────────────────────────────────────────────────────────────────────────╯

dorsal record tag rm

This command removes a tag from a file record. To remove a tag, you must provide its unique tag ID.

You can only remove tags you added.

The tag ID is always displayed alongside the tag, and you can get it by running dorsal record get on the file hash.

Example

  1. First, use dorsal record get to show the record, including all tags.:

    dorsal record get c77c02b50c88d1ec8e07abadb18d104de5146e3eb7b434a67985e99ba84badb3

    In this example we will remove the genre tag, which has the tag ID of 6903b66b3dd03157960df671

    ```text 🔎 Searching for file record with hash c77c02b50c88d1ec8e07abadb18d104de5146e3eb7b434a67985e99ba84badb3 ╭────────────────────── File Record: Snow Crash - Neal Stephenson.epub ──────────────────────╮ │ │ │ Hashes │ │ SHA-256: c77c02b50c88d1ec8e07abadb18d104de5146e3eb7b434a67985e99ba84badb3 │ │ TLSH: T135F422335C5D4B84C60F2EB9250778585A7C83D9EA10D80BAFB3D6A524F16F1172F3AA │ │ │ │ File Info │ │ Name: Snow Crash - Neal Stephenson.epub │ │ Size: 757 KiB │ │ Media Type: application/epub+zip │ │ │ │ Tags │ │ genre: Sci-Fi (private) [id: 6903b66b3dd03157960df671] │ │ │ │ Ebook Info │ │ title: Snow Crash │ │ authors: Neal Stephenson │ │ publisher: Random House Publishing Group │ │ language: eng │ │ rights: Copyright 1992 │ │ isbn: 9780553898194 │ │ cover_path: OEBPS/images/Step_9780553898194_epub_cvi_r1.jpg │ │ publication_date: 2003-08-26T00:00:00Z │ │ │ │ │ ╰────────────────────────────────────────────────────────────────────────────────────────────╯

  2. Run dorsal record tag rm with the file hash and mandatory --tag-id argument

    dorsal record tag rm c77c02b50c88d1ec8e07abadb18d104de5146e3eb7b434a67985e99ba84badb3 --tag-id 6903b66b3dd03157960df671

    This will then inform you of the success.

    🗑️  Removing tag 6903b66b3dd03157960df671 from file c77c02b50c88d1ec8e07abadb18d104de5146e3eb7b434a67985e99ba84badb3...
✅ Successfully removed tag '6903b66b3dd03157960df671'.

  3. We can run dorsal record get again to confirm the tag is now gone.

    dorsal record get c77c02b50c88d1ec8e07abadb18d104de5146e3eb7b434a67985e99ba84badb3

    And we can see that the tag is no longe present.

    ```text 🔎 Searching for file record with hash c77c02b50c88d1ec8e07abadb18d104de5146e3eb7b434a67985e99ba84badb3 ╭────────────────────── File Record: Snow Crash - Neal Stephenson.epub ──────────────────────╮ │ │ │ Hashes │ │ SHA-256: c77c02b50c88d1ec8e07abadb18d104de5146e3eb7b434a67985e99ba84badb3 │ │ TLSH: T135F422335C5D4B84C60F2EB9250778585A7C83D9EA10D80BAFB3D6A524F16F1172F3AA │ │ │ │ File Info │ │ Name: Snow Crash - Neal Stephenson.epub │ │ Size: 757 KiB │ │ Media Type: application/epub+zip │ │ │ │ Tags │ │ │ │ Ebook Info │ │ title: Snow Crash │ │ authors: Neal Stephenson │ │ publisher: Random House Publishing Group │ │ language: eng │ │ rights: Copyright 1992 │ │ isbn: 9780553898194 │ │ cover_path: OEBPS/images/Step_9780553898194_epub_cvi_r1.jpg │ │ publication_date: 2003-08-26T00:00:00Z │ │ │ │ │ ╰────────────────────────────────────────────────────────────────────────────────────────────╯

Options

  • Output the raw JSON API response:

    dorsal record tag rm <hash> --tag-id "tag_abc123" --json

CLI Docs

 Usage: dorsal record tag rm [OPTIONS] HASH_STRING                              

 Removes a specific tag from a file record using its unique ID.               

╭─ Arguments ─────────────────────────────────────────────────────────────────╮
│ * hash_string      TEXT  The hash of the file record. [required]            │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────╮
│ --tag-id    TEXT  The unique ID of the tag to remove. [required]            │
│ --json            Output result as a raw JSON object.                       │
│ --help            Show this message and exit.                               │
╰─────────────────────────────────────────────────────────────────────────────╯

➡️ Continue to: dorsal collection Guide