Commands
sync is the only command that calls GitHub. list, package list, package show, report, audit, and tui read the local cache.
list and package list show the same table. --view NAME on list, package list, package show, report, audit, and tui selects a saved view for that command. It does not write the file. An unknown name exits 2.
Package
| Command | Behaviour |
|---|---|
ghcr-intel list |
Show the cached table. Same as package list |
ghcr-intel package add OWNER/NAME |
Add an image. Optional --group, --profile, and repeated --tag. No GitHub call |
ghcr-intel package list |
Show the cached table |
ghcr-intel package show OWNER NAME |
Show one image. The owner and the name are two arguments |
ghcr-intel package remove OWNER/NAME |
Remove an image from the list. Cached data is kept |
ghcr-intel package set-group OWNER/NAME GROUP |
Assign a group. Groups do not change which checks run |
ghcr-intel package set-profile OWNER/NAME PROFILE |
Choose the checks for one image |
ghcr-intel package enable OWNER/NAME |
Include an image in synchronisation again |
ghcr-intel package disable OWNER/NAME |
Keep an image in the list and skip synchronisation |
--tag on package add is a local label. It is not a ghcr.io image tag. Repeat the option to add more than one label. Those labels appear in the Tags column. ghcr.io tag names appear in Image tags.
package disable writes enabled: false on that image. The image stays in the file and list still shows it. The Enabled value is no. sync does not request it. package enable writes enabled: true.
package show exits 5 when the image is not configured.
Sync, Report, and Audit
| Command | Behaviour |
|---|---|
ghcr-intel sync |
Refresh stale or missing information. A terminal shows a progress bar |
ghcr-intel sync --force |
Ignore cache freshness and sync.interval |
ghcr-intel report |
Write a report of the selected list. The default is Markdown |
ghcr-intel audit |
Show images with a failing check |
ghcr-intel tui |
Open the terminal interface on the cached view |
On a terminal, sync shows a progress bar on stderr. Otherwise one line is printed when the completed count changes, and again when a rate-limit wait starts or ends. The request count on that line is the total for the run.
sync.concurrency images run at once. The default is 10. sync --concurrency N overrides that number for one run. A value below 1 exits 2.
list, sync, and report accept --group and --profile. The match ignores case. sync then skips disabled images in that set.
When GitHub names a wait, sync pauses and the progress line says waiting for GitHub rate limit. A 429 that does not name a wait is retried immediately.
report uses the selected list, the human labels, and display.date_format. Markdown, JSON, and CSV use the same cell text. The Markdown title is # GHCR Intel Report. A cell escapes | as \| and a newline as <br>.
report --output FILE writes that text to a file. The file stays plain.
audit includes images whose status is Stale, Error, Unavailable, or Forbidden, and images whose architectures check failed. It accepts table and json only.
--fail-on-checks on list, package list, package show, sync, report, and audit exits 6 when that set is non-empty.
Configuration Commands
| Command | Behaviour |
|---|---|
ghcr-intel config init |
Write the three default files. --force overwrites existing files |
ghcr-intel config show |
Print the resolved settings. The token is not included |
ghcr-intel config validate |
Load the files and report the package count |
ghcr-intel config paths |
Print the configuration and cache paths |
ghcr-intel profile list |
List profile names |
ghcr-intel profile tree |
Show each profile and its parent |
ghcr-intel profile validate |
Resolve every profile |
ghcr-intel profile show NAME |
Show the effective checks for one profile |
ghcr-intel cache info |
Show the cache path, size, and row counts |
ghcr-intel cache clear --yes |
Delete cached documents and sync runs. The image list stays |
ghcr-intel cache vacuum |
Rebuild the SQLite file |
config init keeps a file that already exists unless --force is passed. When nothing is written, the command exits 2.
profile show prints each check as true or false after inheritance. The check names are metadata, tags, digests, architectures, and stale.
Formats
JSON, CSV, and Markdown stay plain. The coloured table is the human view.
| Command | --format values |
Default |
|---|---|---|
list |
table, json, csv, markdown |
table |
package list |
table, json, csv, markdown |
table |
package show |
table, json, csv, markdown |
table |
report |
table, json, csv, markdown |
markdown |
audit |
table, json |
table |
An unknown format exits 2.
A terminal table uses colour. Headers are bold cyan. The detail field column is cyan. Public is green, private is magenta, a stale or forbidden value is yellow, and an error is red.
JSON, CSV, Markdown, and a report file stay plain.
Shared Flags
| Flag | Behaviour |
|---|---|
--config |
Use this main configuration file instead of the default path |
--verbose |
Write informational logs to stderr |
--debug |
Write debug logs to stderr. A GitHub token is redacted |
--version |
Print the version and exit |
Terminal Interface
With no arguments, an interactive terminal opens the terminal interface on the cached view. Otherwise the help text is printed.
The summary and the search box sit under the header. Search filters the owner, package name, and description.
| Key | Action |
|---|---|
| Enter | Open the image detail |
| Escape | Close a popup, cancel a sync, or clear search |
/ |
Search the owner, package, and description |
r |
Synchronise |
p |
Profiles |
c |
Configuration paths |
v |
Pick a saved view for this session |
Ctrl+Q |
Quit |
v does not write the file. q alone does not quit, because the search field uses that key.
ghcr-intel tui --view tags opens on the shipped example view.
Exit Codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General failure |
| 2 | Configuration or usage |
| 3 | Authentication |
| 4 | Sync incomplete or cancelled |
| 5 | Package is not configured |
| 6 | --fail-on-checks, and at least one check failed |