📌 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.