Skip to content

File Pinning

Jump to bottom
Scott E. Graves edited this page Oct 16, 2025 · 1 revision

📌 File Pinning

Pinning keeps specific files cached locally and protected from eviction. It's per-file metadata (stored in the mount's meta DB) and is supported on S3, Sia, and Encrypt providers.

Not supported on Remote Mount.

✅ Provider Compatibility

Provider Pin Support
S3 Yes
Sia Yes
Encrypt Yes
Remote Mount No

On Remote Mount, pin/unpin/status/list endpoints are not implemented; CLI pinning commands will return an error (HTTP error / unsupported).

What “pinned” means

  • Pinned files are marked with pinned=true in the mount's metadata database.
  • Cache eviction skips pinned files.
  • Pinning does not auto-download content in v2.0.x; the file is retained after it's cached by normal access.
    • v2.1.x and above, by default, will auto-download files not residing in cache.
    • In configuration, change AutoDownloadOnPin to false if you wish to keep legacy behavior.

To prefetch in v2.0.x, read the file once (e.g., cat, open/scan, copy).

CLI

These commands hit the local management HTTP API of the active S3/Sia/Encrypt mount.

  • Pin a file

    repertory -pf "/path/to/file.ext"

  • Unpin a file

    repertory -uf "/path/to/file.ext"

  • Check pinned status

    repertory -ps "/path/to/file.ext"
# → { "pinned": true|false }

  • List all pinned files

    repertory -gpf
# → { "items": [ "/path/one", "/path/two", ... ] }

Arguments: -pf, -uf, -ps take an API path (virtual path inside the mount), e.g., "/docs/report.pdf".
Auth (optional): --user, --password.
Ports (defaults): Sia 20000, S3 20100, Encrypt 20001.

Remote Mount: pin CLI calls are unsupported and will error.

REST API (S3/Sia/Encrypt)

Base: http://localhost:<api_port>/api/v1/ (Basic Auth if configured)

List pinned

GET get_pinned_files → 200 OK

{ "items": [ "/path/one", "/path/two" ] }

Pinned status

GET pinned_status?api_path=/path/to/file.ext → 200 OK

{ "pinned": true }

Errors: 500 on provider/meta error.

Pin file

POST pin_file (form: api_path=/path/to/file.ext)
Responses: 200 OK on success, 404 Not Found if not a file or doesn't exist, 500 on error.

Unpin file

POST unpin_file (form: api_path=/path/to/file.ext)
Responses: 200 OK on success, 404 Not Found if not a file or doesn't exist, 500 on error.

Success bodies are empty JSON; rely on the HTTP status code.

Examples (S3/Sia/Encrypt)

# Pin a file
repertory -pf "/media/photos/2024/trip.jpg"

# Verify status
repertory -ps "/media/photos/2024/trip.jpg"
# { "pinned": true }

# List all pins
repertory -gpf
# { "items": [ "/media/photos/2024/trip.jpg", ... ] }

Windows (PowerShell):

repertory -pf "/Docs/Quarterly Report.pdf"
repertory -uf "/Docs/Quarterly Report.pdf"

Troubleshooting

  • Remote Mount: Pinning is unsupported; CLI returns an HTTP error/unsupported operation.
  • 404 Not Found: Wrong path, item isn't a file, or missing. Use -gi (item info) or -gdi (directory list) to verify paths.
  • 401/403: API auth enabled — pass --user and --password or set in config.
  • Pinned but not in local cache yet: Pin prevents eviction; read once to cache locally for v2.0.x. For v2.1.x+, ensure configuration option AutoDownloadOnPin is set to true.

Clone this wiki locally