fm registry
Reference for the fm registry command group (auto-generated from fm registry --help).
fm registry
text
Enable your tenant's container registry, manage the credentials used to push and
pull images, browse the repositories and images it holds, and mirror public
registries through pull-through caches.
Usage:
fm registry [command]
Aliases:
registry, reg
Available Commands:
cache Manage the pull-through caches in your container registry
credential Manage container registry credentials
enable Enable this tenant's container registry
image Browse the images in a repository
repository Browse the repositories in your registry
retention Manage this tenant's image retention policy
status Show this tenant's container registry status
Flags:
-h, --help help for registry
Global Flags:
--config string config file (default is $HOME/.fm/config.yaml)
-d, --debug enable debug/verbose output
--no-color disable colored output
-o, --output string output format: table, json, yaml, wide (default "table")
-q, --quiet suppress non-essential output
--tenant string tenant ID to operate on (overrides the active/default tenant; also FM_TENANT)
Use "fm registry [command] --help" for more information about a command.fm registry cache
text
Manage this tenant's pull-through caches.
A pull-through cache is a namespace that mirrors ONE public registry on demand:
you pull through it, and it fetches from the upstream and keeps a copy. A tenant
wanting three upstreams creates three caches.
The upstream is chosen by KEY from a list the platform serves — never by URL, and
there is no field for one. `fm registry cache list` shows the keys on offer.
CACHED IMAGES COUNT AGAINST YOUR STORAGE ALLOWANCE. It is one quota and one
meter, shared with your repository namespace, and a cache fills on PULL — so it
can consume your allowance with no push from you.
`fm registry cache repository` and `fm registry cache image` show what one cache
holds, and remove single images from it.
Usage:
fm registry cache [command]
Aliases:
cache, caches
Available Commands:
create Create a pull-through cache for one upstream registry
delete Delete a pull-through cache
image Browse and remove the images in a pull-through cache
list List your pull-through caches and the upstreams on offer
repository Browse the repositories one pull-through cache holds
Flags:
-h, --help help for cache
Global Flags:
--config string config file (default is $HOME/.fm/config.yaml)
-d, --debug enable debug/verbose output
--no-color disable colored output
-o, --output string output format: table, json, yaml, wide (default "table")
-q, --quiet suppress non-essential output
--tenant string tenant ID to operate on (overrides the active/default tenant; also FM_TENANT)
Use "fm registry cache [command] --help" for more information about a command.fm registry cache create
text
Create a pull-through cache that mirrors ONE public registry.
The upstream is a KEY from the list the platform serves, which
`fm registry cache list` shows — never a URL, and there is no flag for one.
One cache per upstream; a tenant wanting three upstreams creates three caches.
CREDENTIALS ARE YOURS, AT THE UPSTREAM. Some upstreams require them — Docker Hub
does, because an anonymous mirror of it spends an allowance shared with every
other customer on the same address. `fm registry cache list` marks which, and
the platform enforces it either way.
Supply the password one of three ways:
--password-stdin read it from standard input; the safest for scripts
(no flag) typed at a prompt, not echoed, when fm is run interactively
--password LAST RESORT: a value on the command line is visible to
anyone who can run `ps` on the machine, and is kept in your
shell history
They are write-only: nothing reads them back, and THERE IS NO UPDATE — change
them by deleting the cache and creating it again. They are not checked here
either, so a wrong password surfaces later as a failed pull.
Pull through the cache with the SAME credential that reaches your repository
namespace: `docker login` is per host, and credentials you already hold are
extended onto a new cache automatically.
CACHED IMAGES COUNT AGAINST YOUR STORAGE ALLOWANCE, which is shared with your
repository namespace and fills on PULL.
Usage:
fm registry cache create <upstream> [flags]
Flags:
-h, --help help for create
--password ps your own password or access token at the upstream (LAST RESORT: visible to ps and kept in shell history — prefer --password-stdin, or the prompt)
--password-stdin read the upstream password from standard input
--username string your own username at the upstream registry (required by some upstreams)
Global Flags:
--config string config file (default is $HOME/.fm/config.yaml)
-d, --debug enable debug/verbose output
--no-color disable colored output
-o, --output string output format: table, json, yaml, wide (default "table")
-q, --quiet suppress non-essential output
--tenant string tenant ID to operate on (overrides the active/default tenant; also FM_TENANT)fm registry cache delete
text
Delete one of this tenant's pull-through caches.
THE CACHED IMAGES GO WITH IT, and so do the upstream credentials stored for it.
Nothing you created is lost — every byte in a cache is a copy of something still
at the upstream, and a later pull re-fetches it — but anything pulling through
this path stops working until the cache is created again, and your stored-bytes
figure falls as the content goes.
A cache whose upstream is no longer offered is still deletable by its key.
Usage:
fm registry cache delete <upstream> [flags]
Aliases:
delete, rm, remove
Flags:
--force skip confirmation prompt
-h, --help help for delete
Global Flags:
--config string config file (default is $HOME/.fm/config.yaml)
-d, --debug enable debug/verbose output
--no-color disable colored output
-o, --output string output format: table, json, yaml, wide (default "table")
-q, --quiet suppress non-essential output
--tenant string tenant ID to operate on (overrides the active/default tenant; also FM_TENANT)fm registry cache image
text
Browse and remove the images in a pull-through cache
Usage:
fm registry cache image [command]
Aliases:
image, images, artifact, artifacts
Available Commands:
delete Remove one image from a pull-through cache
list List the images in one repository of a pull-through cache
Flags:
-h, --help help for image
Global Flags:
--config string config file (default is $HOME/.fm/config.yaml)
-d, --debug enable debug/verbose output
--no-color disable colored output
-o, --output string output format: table, json, yaml, wide (default "table")
-q, --quiet suppress non-essential output
--tenant string tenant ID to operate on (overrides the active/default tenant; also FM_TENANT)
Use "fm registry cache image [command] --help" for more information about a command.fm registry cache image delete
text
Remove ONE image from one of this tenant's pull-through caches.
USE IT TO FREE SPACE. A cache already trims images nobody has pulled for 7 days;
this frees one now, in a cache that is at or near its storage cap.
It is NOT how to refresh an image. A pull by tag already asks the upstream for
the current image on every pull, so a copy is only served stale while the
upstream is unreachable or refusing (rate-limiting, say) — and in exactly that
case the copy is what keeps the pull working.
NOTHING YOU MADE IS LOST: every image in a cache is a copy of one at the
upstream, and the next pull of it through the cache fetches it again. BUT WHILE
THE UPSTREAM IS UNREACHABLE OR RATE-LIMITING, A REMOVED IMAGE CANNOT BE FETCHED:
pulls of it fail until the upstream answers again. So do not remove an image a
workload depends on while its upstream is refusing you.
The image goes with every tag in the cache that points at it. The cache itself,
its upstream and its stored upstream credentials are untouched; removing the
whole cache is `fm registry cache delete`.
IT TAKES A DIGEST, NOT A TAG, for the reason `fm registry image delete` does: a
tag moves, and a digest names one image for ever. Copy it from
`fm registry cache image list <upstream> <repository> -o json`.
The cache's storage figure moves straight away, by less than the size in the
table when layers are shared with other images in the cache;
`fm registry cache list` shows it.
A per-platform part of a multi-architecture image cannot be deleted on its own.
Delete the index and its parts go with it.
Usage:
fm registry cache image delete <upstream> <repository> <digest> [flags]
Aliases:
delete, rm, remove
Flags:
--force skip confirmation prompt
-h, --help help for delete
Global Flags:
--config string config file (default is $HOME/.fm/config.yaml)
-d, --debug enable debug/verbose output
--no-color disable colored output
-o, --output string output format: table, json, yaml, wide (default "table")
-q, --quiet suppress non-essential output
--tenant string tenant ID to operate on (overrides the active/default tenant; also FM_TENANT)fm registry cache image list
text
List the images (artifacts) in one repository of a pull-through cache.
The upstream is the cache's KEY, as `fm registry cache list` shows it, and the
repository is named RELATIVE TO THE CACHE, as
`fm registry cache repository list <upstream>` shows it — `library/nginx`.
CACHED is when the cache fetched and stored its copy — the pull that filled it —
not when the image was pushed to the upstream. A copy fetched again after a
delete carries the new time.
SIZES DO NOT ADD UP, for the same reason as on `fm registry image list`: shared
layers are counted in full for every image using them. The deduplicated figure
for the cache is the STORAGE column of `fm registry cache list`.
Paging works exactly as on `fm registry image list`: --page/--page-size to walk
the pages yourself, or --all to fetch every page from the first (it cannot be
combined with --page, and it fails rather than truncate). The order is
unspecified, so --all is a snapshot; repeats are removed by digest. Digests are
shortened in the table; -o json prints them whole.
Usage:
fm registry cache image list <upstream> <repository> [flags]
Flags:
--all fetch every page, starting at the first (cannot be combined with --page)
-h, --help help for list
--page int page of results to fetch (1-based) (default 1)
--page-size int images per page (0 uses the server's default; the server caps how large this may be)
Global Flags:
--config string config file (default is $HOME/.fm/config.yaml)
-d, --debug enable debug/verbose output
--no-color disable colored output
-o, --output string output format: table, json, yaml, wide (default "table")
-q, --quiet suppress non-essential output
--tenant string tenant ID to operate on (overrides the active/default tenant; also FM_TENANT)fm registry cache list
text
List this tenant's pull-through caches.
It also shows the upstreams you could still add and how many caches you have room
for, because those are what you need before creating one — the set of upstreams
is served by the platform rather than built into fm, so this listing is the
authoritative answer to "what can I mirror?".
A cache whose upstream has since been withdrawn keeps working and stays
deletable. It is shown by its key and is simply no longer on the offer list.
Usage:
fm registry cache list [flags]
Flags:
-h, --help help for list
Global Flags:
--config string config file (default is $HOME/.fm/config.yaml)
-d, --debug enable debug/verbose output
--no-color disable colored output
-o, --output string output format: table, json, yaml, wide (default "table")
-q, --quiet suppress non-essential output
--tenant string tenant ID to operate on (overrides the active/default tenant; also FM_TENANT)fm registry cache repository
text
Browse the repositories one pull-through cache holds
Usage:
fm registry cache repository [command]
Aliases:
repository, repo, repos, repositories
Available Commands:
list List the repositories one pull-through cache holds
Flags:
-h, --help help for repository
Global Flags:
--config string config file (default is $HOME/.fm/config.yaml)
-d, --debug enable debug/verbose output
--no-color disable colored output
-o, --output string output format: table, json, yaml, wide (default "table")
-q, --quiet suppress non-essential output
--tenant string tenant ID to operate on (overrides the active/default tenant; also FM_TENANT)
Use "fm registry cache repository [command] --help" for more information about a command.fm registry cache repository list
text
List the repositories one of this tenant's pull-through caches holds — the
images it has fetched from its upstream on a pull.
The upstream is the cache's KEY, as `fm registry cache list` shows it.
Names are RELATIVE TO THE CACHE: a Docker Hub cache lists `library/nginx`, which
you pull as `<pull path>/library/nginx:<tag>` and pass to
`fm registry cache image list <upstream> library/nginx`.
ARTIFACTS counts manifests rather than tags, exactly as on
`fm registry repository list`.
Usage:
fm registry cache repository list <upstream> [flags]
Flags:
-h, --help help for list
Global Flags:
--config string config file (default is $HOME/.fm/config.yaml)
-d, --debug enable debug/verbose output
--no-color disable colored output
-o, --output string output format: table, json, yaml, wide (default "table")
-q, --quiet suppress non-essential output
--tenant string tenant ID to operate on (overrides the active/default tenant; also FM_TENANT)fm registry credential
text
Manage container registry credentials
Usage:
fm registry credential [command]
Aliases:
credential, credentials, cred, creds
Available Commands:
create Mint a container registry credential
delete Revoke a container registry credential
get Show one container registry credential
list List container registry credentials
Flags:
-h, --help help for credential
Global Flags:
--config string config file (default is $HOME/.fm/config.yaml)
-d, --debug enable debug/verbose output
--no-color disable colored output
-o, --output string output format: table, json, yaml, wide (default "table")
-q, --quiet suppress non-essential output
--tenant string tenant ID to operate on (overrides the active/default tenant; also FM_TENANT)
Use "fm registry credential [command] --help" for more information about a command.fm registry credential create
text
Mint a container registry credential.
The secret is displayed ONCE. There is no rotation endpoint and no retrievable
copy anywhere, so store it now — a lost secret is recovered by revoking the
credential and minting a new one.
The credential reaches every namespace this tenant owns, because `docker login`
is per host and you hold one credential for the endpoint.
Usage:
fm registry credential create [flags]
Flags:
--capability string what the credential may do: pull or push (push implies pull) (default "pull")
-h, --help help for create
--name string your own label for the credential (required)
Global Flags:
--config string config file (default is $HOME/.fm/config.yaml)
-d, --debug enable debug/verbose output
--no-color disable colored output
-o, --output string output format: table, json, yaml, wide (default "table")
-q, --quiet suppress non-essential output
--tenant string tenant ID to operate on (overrides the active/default tenant; also FM_TENANT)fm registry credential delete
text
Revoke a container registry credential. Any client still using it stops working immediately.
Usage:
fm registry credential delete <id> [flags]
Aliases:
delete, revoke
Flags:
--force skip confirmation prompt
-h, --help help for delete
Global Flags:
--config string config file (default is $HOME/.fm/config.yaml)
-d, --debug enable debug/verbose output
--no-color disable colored output
-o, --output string output format: table, json, yaml, wide (default "table")
-q, --quiet suppress non-essential output
--tenant string tenant ID to operate on (overrides the active/default tenant; also FM_TENANT)fm registry credential get
text
Show one container registry credential. The secret is never returned.
Usage:
fm registry credential get <id> [flags]
Flags:
-h, --help help for get
Global Flags:
--config string config file (default is $HOME/.fm/config.yaml)
-d, --debug enable debug/verbose output
--no-color disable colored output
-o, --output string output format: table, json, yaml, wide (default "table")
-q, --quiet suppress non-essential output
--tenant string tenant ID to operate on (overrides the active/default tenant; also FM_TENANT)fm registry credential list
text
List this tenant's container registry credentials. Secrets are never listed.
Usage:
fm registry credential list [flags]
Flags:
-h, --help help for list
Global Flags:
--config string config file (default is $HOME/.fm/config.yaml)
-d, --debug enable debug/verbose output
--no-color disable colored output
-o, --output string output format: table, json, yaml, wide (default "table")
-q, --quiet suppress non-essential output
--tenant string tenant ID to operate on (overrides the active/default tenant; also FM_TENANT)fm registry enable
text
Enable this tenant's container registry.
This is the explicit opt-in that creates your namespace and the billable state
that comes with it. Nothing about the registry is configurable: the namespace is
derived from your tenant id and never changes, so image references you pin stay
valid across a tenant rename.
Enabling cannot currently be undone — teardown belongs to tenant closure.
Usage:
fm registry enable [flags]
Flags:
-h, --help help for enable
Global Flags:
--config string config file (default is $HOME/.fm/config.yaml)
-d, --debug enable debug/verbose output
--no-color disable colored output
-o, --output string output format: table, json, yaml, wide (default "table")
-q, --quiet suppress non-essential output
--tenant string tenant ID to operate on (overrides the active/default tenant; also FM_TENANT)fm registry image
text
Browse the images in a repository
Usage:
fm registry image [command]
Aliases:
image, images, artifact, artifacts
Available Commands:
delete Delete one image from a repository
list List the images in a repository
Flags:
-h, --help help for image
Global Flags:
--config string config file (default is $HOME/.fm/config.yaml)
-d, --debug enable debug/verbose output
--no-color disable colored output
-o, --output string output format: table, json, yaml, wide (default "table")
-q, --quiet suppress non-essential output
--tenant string tenant ID to operate on (overrides the active/default tenant; also FM_TENANT)
Use "fm registry image [command] --help" for more information about a command.fm registry image delete
text
Delete ONE image from one of this tenant's repositories.
This is the only way to free space against your storage cap.
THE IMAGE GOES, NOT JUST THE TAG. Every tag pointing at it goes with it, and so
does the manifest — after this the image cannot be pulled by name OR by digest.
There is no untag command: removing a label while leaving the content pullable by
digest frees nothing and only looks like a delete.
IT TAKES A DIGEST, NOT A TAG, and that is a safety property rather than an
inconvenience. A tag moves: asking to delete "the one tagged v1" a moment after
CI re-pushed v1 destroys an image you meant to keep, and nothing would tell you.
Copy the digest from `fm registry image list <repository> -o json`, which prints
it whole.
YOUR STORAGE FIGURE MOVES STRAIGHT AWAY, BUT BY LESS THAN THE SIZE IN THE TABLE.
Layers shared with your other images in the same namespace are counted once and
stay counted; only what nothing else references comes back. Re-run `fm registry status` to see the real
figure — do not compute it from the size column.
A per-platform part of a multi-architecture image cannot be deleted on its own.
Delete the index and its parts go with it.
Usage:
fm registry image delete <repository> <digest> [flags]
Aliases:
delete, rm, remove
Flags:
--force skip confirmation prompt
-h, --help help for delete
Global Flags:
--config string config file (default is $HOME/.fm/config.yaml)
-d, --debug enable debug/verbose output
--no-color disable colored output
-o, --output string output format: table, json, yaml, wide (default "table")
-q, --quiet suppress non-essential output
--tenant string tenant ID to operate on (overrides the active/default tenant; also FM_TENANT)fm registry image list
text
List the images (artifacts) in one of this tenant's repositories.
The repository is named the way `fm registry repository list` shows it — relative
to your namespace, so `web/api` rather than the full pull path.
SIZES DO NOT ADD UP. Each row is that image's own size, and layers shared with
another image in the same namespace are counted once but reported in full for
every image using them. Summing the column overstates what your registry holds,
and deleting an image does not free the number beside it. The deduplicated
figure — the one your storage quota is applied to, counted per namespace — is
the one in `fm registry status`.
A row tagged <untagged> has no tag pointing at it: a later push moved that tag
onto a new image and left this one behind. It cannot be pulled by name, and it
still counts against your quota, so it is usually what you are looking for when
clearing space.
Results are paginated. Pass --page/--page-size to walk them yourself, or --all to
fetch every page. --all starts at the first page and cannot be combined with
--page. Digests are shortened in the table; -o json prints them whole.
THE ORDER IS UNSPECIFIED — the API does not sort and does not promise one — so a
--all walk is a SNAPSHOT rather than a transaction: a push landing mid-walk moves
the page boundary. Repeats are removed by digest; an image that moves backwards
across a boundary while the walk is running can still be missed.
Usage:
fm registry image list <repository> [flags]
Flags:
--all fetch every page, starting at the first (cannot be combined with --page)
-h, --help help for list
--page int page of results to fetch (1-based) (default 1)
--page-size int images per page (0 uses the server's default; the server caps how large this may be)
Global Flags:
--config string config file (default is $HOME/.fm/config.yaml)
-d, --debug enable debug/verbose output
--no-color disable colored output
-o, --output string output format: table, json, yaml, wide (default "table")
-q, --quiet suppress non-essential output
--tenant string tenant ID to operate on (overrides the active/default tenant; also FM_TENANT)fm registry repository
text
Browse the repositories in your registry
Usage:
fm registry repository [command]
Aliases:
repository, repo, repos, repositories
Available Commands:
list List the repositories in your registry
Flags:
-h, --help help for repository
Global Flags:
--config string config file (default is $HOME/.fm/config.yaml)
-d, --debug enable debug/verbose output
--no-color disable colored output
-o, --output string output format: table, json, yaml, wide (default "table")
-q, --quiet suppress non-essential output
--tenant string tenant ID to operate on (overrides the active/default tenant; also FM_TENANT)
Use "fm registry repository [command] --help" for more information about a command.fm registry repository list
text
List the repositories in this tenant's registry namespace.
Names are RELATIVE to your namespace — `web/api`, not the full pull path — and
that is the form `fm registry image list` takes.
ARTIFACTS counts manifests rather than tags: an image pushed under three tags is
one artifact, and a manifest whose tag was later reused is still counted after it
stops being reachable by name. `fm registry image list <repository>` shows which
of them those are.
Usage:
fm registry repository list [flags]
Flags:
-h, --help help for list
Global Flags:
--config string config file (default is $HOME/.fm/config.yaml)
-d, --debug enable debug/verbose output
--no-color disable colored output
-o, --output string output format: table, json, yaml, wide (default "table")
-q, --quiet suppress non-essential output
--tenant string tenant ID to operate on (overrides the active/default tenant; also FM_TENANT)fm registry retention
text
Manage this tenant's image retention policy.
One policy covers every repository in this tenant's registry, and each
repository is evaluated on its own. The policy runs nightly, between 00:00 and 06:00 UTC.
Pull-through caches are not affected.
Usage:
fm registry retention [command]
Available Commands:
delete Remove the image retention policy
get Show the image retention policy
set Replace the image retention policy
Flags:
-h, --help help for retention
Global Flags:
--config string config file (default is $HOME/.fm/config.yaml)
-d, --debug enable debug/verbose output
--no-color disable colored output
-o, --output string output format: table, json, yaml, wide (default "table")
-q, --quiet suppress non-essential output
--tenant string tenant ID to operate on (overrides the active/default tenant; also FM_TENANT)
Use "fm registry retention [command] --help" for more information about a command.fm registry retention delete
text
Remove this tenant's image retention policy. Images are then kept until you delete them.
Usage:
fm registry retention delete [flags]
Aliases:
delete, rm, remove
Flags:
--force skip confirmation prompt
-h, --help help for delete
Global Flags:
--config string config file (default is $HOME/.fm/config.yaml)
-d, --debug enable debug/verbose output
--no-color disable colored output
-o, --output string output format: table, json, yaml, wide (default "table")
-q, --quiet suppress non-essential output
--tenant string tenant ID to operate on (overrides the active/default tenant; also FM_TENANT)fm registry retention get
text
Show the image retention policy
Usage:
fm registry retention get [flags]
Flags:
-h, --help help for get
Global Flags:
--config string config file (default is $HOME/.fm/config.yaml)
-d, --debug enable debug/verbose output
--no-color disable colored output
-o, --output string output format: table, json, yaml, wide (default "table")
-q, --quiet suppress non-essential output
--tenant string tenant ID to operate on (overrides the active/default tenant; also FM_TENANT)fm registry retention set
text
Replace this tenant's image retention policy.
set REPLACES THE WHOLE POLICY. A rule you do not give is removed, which means
nothing in that class is deleted: with only --keep-last-tagged, untagged images
are never deleted; with only --delete-untagged-after-days, tagged images are
never deleted. Give both flags to keep both rules.
--keep-last-tagged N keep the N most recently pushed tagged images
in each repository and delete older ones (1-1000)
--delete-untagged-after-days X delete untagged images last pushed more than
X days ago (1-365)
At least one rule is required. The policy runs nightly, between 00:00 and 06:00 UTC. Deleted images
cannot be recovered.
When the new policy deletes more than the current one (no policy before, a rule
newly switched on, or a lower number), set shows both and asks for confirmation.
--force skips the prompt; without a terminal, set refuses unless --force is given.
Usage:
fm registry retention set [flags]
Examples:
# Keep the 10 newest tagged images per repository and delete untagged
# images after 7 days
fm registry retention set --keep-last-tagged 10 --delete-untagged-after-days 7
Flags:
--delete-untagged-after-days int delete untagged images last pushed more than X days ago (1-365)
--force skip the confirmation prompt for a stricter policy
-h, --help help for set
--keep-last-tagged int keep the N most recently pushed tagged images per repository (1-1000)
Global Flags:
--config string config file (default is $HOME/.fm/config.yaml)
-d, --debug enable debug/verbose output
--no-color disable colored output
-o, --output string output format: table, json, yaml, wide (default "table")
-q, --quiet suppress non-essential output
--tenant string tenant ID to operate on (overrides the active/default tenant; also FM_TENANT)fm registry status
text
Show this tenant's container registry status
Usage:
fm registry status [flags]
Flags:
-h, --help help for status
Global Flags:
--config string config file (default is $HOME/.fm/config.yaml)
-d, --debug enable debug/verbose output
--no-color disable colored output
-o, --output string output format: table, json, yaml, wide (default "table")
-q, --quiet suppress non-essential output
--tenant string tenant ID to operate on (overrides the active/default tenant; also FM_TENANT)