CLI reference: sparkwing cache

CLI reference: sparkwing cache

Every sparkwing cache command, flag, and argument, generated from the CLI's own command registry. All command groups are indexed in cli-reference.md.

sparkwing cache

Inspect or trim the compiled pipeline binary cache

Compiled pipeline binaries are keyed by their source fingerprint and stored under $SPARKWING_HOME/cache/pipelines. Automatic pruning after compilation keeps recently used entries within the configured byte and entry limits. Use these commands to inspect entries or reclaim space.

Subcommands

• info -- Print cache dir, size, ceilings, and recent entries
• prune -- Evict least recently used binaries down to the ceilings
• explain -- Show a pipeline's cache key and the inputs behind it

Examples

# See what is cached
sparkwing cache info

# Reclaim space now
sparkwing cache prune

sparkwing cache explain

Show a pipeline's cache key and the inputs behind it

Prints the cache key for a pipeline module, whether that key is already cached, and every input that produced it -- the Go toolchain, the platform, the module tree, each local replace target, a covering go.work, and the resolved module pins -- each with its own digest and how much it covered.

File counts show how many files were excluded because Git ignores them. Edits to excluded files leave the cache key unchanged.

When other cached entries came from the same checkout, each is listed with the inputs that differ from the current key. That is the direct answer to why a rebuild happened.

Flags

Examples

# Why did this rebuild?
sparkwing cache explain

# Agent-readable
sparkwing cache explain -o json

sparkwing cache info

Print cache dir, size, ceilings, and recent entries

Lists the cache directory, its total size, the configured ceilings, and the most recently used entries with their sizes and last-use times. Entries are ordered by last use, which is what pruning evicts on -- not by when they were built.

Flags

Examples

# Human-readable
sparkwing cache info

# Agent-readable
sparkwing cache info -o json

# Every entry
sparkwing cache info --all

sparkwing cache prune

Evict least recently used binaries down to the ceilings

Removes the least recently used cached binaries until the cache fits both the byte ceiling and the entry ceiling. Defaults come from $SPARKWING_CACHE_MAX_BYTES and $SPARKWING_CACHE_MAX_ENTRIES; either accepts 0 to disable that dimension.

An execution lease protects each running binary. Prune skips active and busy entries, bounds the number examined, and reports observed capacity separately from removed entries. Callers making admission decisions remeasure filesystem capacity after pruning.

Flags

Examples

# Trim to the configured ceilings
sparkwing cache prune

# Trim to a smaller budget
sparkwing cache prune --max-bytes 512MiB

# Reclaim everything
sparkwing cache prune --all