kache sync talks directly to the configured remote. It is useful for explicit CI warm and publish steps.

kache sync                 # pull, then push
kache sync --pull          # download only
kache sync --push          # upload only
kache sync --dry-run       # show the plan
kache sync --all           # ignore pull filtering
kache sync --workspace     # pull discovery for workspace members only
kache sync --allow-partial # report failures but exit successfully

Filtering

Pull and push use different scopes:

• Pull normally lists crates from Cargo.lock in the current directory. With no usable lockfile it falls back to listing the full remote.
• --workspace lists only Cargo workspace members and fails if it cannot resolve the workspace. It conflicts with --all.
• Push uses workspace members from cargo metadata --no-deps. --manifest-path changes this push-side scope only.

Narrowing the initial pull does not disable on-demand dependency restores during a later daemon-backed build.

CI sequence

kache sync --pull
cargo build --release
kache sync --push

A running daemon already uploads new entries in the background. Use explicit push when the runner may exit before those uploads finish or when the daemon is intentionally absent.

Failure behavior

All scheduled operations drain before the command exits. Any transfer or import failure makes the command nonzero unless --allow-partial is set.

The legacy cache.s3_concurrency / KACHE_S3_CONCURRENCY setting controls parallel operations for both S3 and filesystem remotes.

Use --dry-run to inspect the planned crate names and truncated keys. Object sizes are not available from the listing plan.