Interface

What other programs can rely on from lnk storage.

lnk storage

What scripts read of the clouds and the files in them, each as JSON.

lnk storage list --json

[{"name", "kind", "backend", "region", "buckets": [{"resource", "bucket", "encrypted", "remote", "files", "bytes", "owner"}]}], one entry per connected cloud, with each bucket clouds.toml keeps for it, an owner's whether or not the module that keeps the owner is here. A folder without a bucket there is left out. It reads only Link's settings and asks no other module. backend is an rclone cloud's storage type, in rclone's word for it. Read by scripts only.

Each bucket

resource is the bucket's ID, bucket:<id>, minted when Link added the bucket here, or kept from where it was when an owner's folder moved here. bucket is its name in the cloud. owner is null for your own files, else the folder's owner by its ID and name: {"group": "group:<id>", "name"} for a hosted team's folder, and {"workload": "<kind>:<id>", "name"} for what runs, such as an agent or a job. The settings keep no owner's name, so name is its ID as well.

Bucket IDs

Each bucket's ID is reserved in ~/.lnk/safe/storage/ids.toml. A cloud disconnected leaves its buckets, and their IDs stay reserved. When Link deletes a bucket (lnk storage delete), its ID is retired and never given again. A clouds.toml with a bucket that has no ID is refused, naming the entry to remove before connecting that cloud again.

lnk storage list --tree [<path>] --json

{"personal": [...], "<kind>:<id>": [...]}, one key per folder, each owner's by its ID, and only the folder holding <path> when given. Read by scripts only.

Each row

{"path", "size", "here", "clouds": [["<cloud>", "<mark>"], ...]}, here one of here, changed, new, offloaded, a mark one of checked, archived, unchecked, differs, missing.

An owner's buckets

The hidden commands the module that keeps an owner runs to carry the owner's buckets when its folder moves, leaves or is restored. Each names the owner by its ID, --owner <kind>:<id>, which the program running it already holds, and refuses one that isn't an ID; restore and find take a name too, since the owner may not be on this machine yet (Owners' folders). Their output is for that program, so each prints the JSON below with or without --json, while every command a person runs prints JSON only with it.

lnk storage export --owner <kind>:<id>

{"password", "buckets": {"<cloud>": "<bucket>"}}: the owner's buckets here and their password, obscured as rclone keeps it; null without any.

lnk storage adopt --owner <kind>:<id>

Reads {"password" | "plain", "buckets", "credentials"?: {"<cloud>": {"bucket", "credential"}}}; puts the owner's buckets in place here: its encryption on buckets this machine knew, buckets in clouds of the same name, and a cloud <cloud>-<kind>-<id> for it alone from each credential. Nonzero when none is reachable (a wrong password).

lnk storage leave --owner <kind>:<id>

The owner's folder left: its encryption and clouds only for it go, and its buckets stay known.

lnk storage keys --owner <kind>:<id> and revoke

{"<cloud>": {"bucket", "credential"}}: through lnk cloud, a credential reaching only each of the owner's buckets (found by its lnk-folder label), any before replaced; or those credentials gone. Read when its folder moves to a box and back.

lnk storage restore --owner <kind>:<name> --folder <folder>

Finds the owner's buckets in your lnk cloud accounts by their labels (and yours, lnk-owner), asks their encryption password (a hidden question on stderr, which needs a terminal), puts them in place here as adopt does, with a credential reaching only them where a cloud makes one, and pulls its files into <folder>. The name may be its ID's id instead, which picks one when owners of two IDs have the name, and a name they share is refused.

What it prints

{"owner", "buckets": {"<cloud>": "<bucket>"}, "labels": {"<cloud>": {"<name>": "<value>"}}} on stdout, owner its ID, labels each bucket's but those saying whose it is, and all else on stderr.

lnk storage label --owner <kind>:<id> <name>=<value>...

{"<cloud>": "<bucket>"}: through lnk cloud, the labels added to each of the owner's buckets (found by its lnk-folder label, never one labelled as another login's), a bucket it couldn't label said on stderr and left out.

What it refuses

A label not of Link's (lnk-), one that says whose a bucket is (lnk-folder, lnk-folder-name, lnk-owner), and names or values beyond 63 lowercase letters, digits, - and _.

lnk storage find [--owner <kind>:<name>]

[{"cloud", "bucket", "place", "owner", "name"}]: owners' buckets in your lnk cloud accounts, by their labels (and yours, lnk-owner), only the named owner's with --owner.