CLI Reference

Command-line interface

On first run, the tool prompts for configuration (database path and kernel storage directory). These are saved to ~/.config/spice-kernel-db/config.toml. All commands share a --db option to override the configured database path.

`scan`

Recursively scan a directory and register all kernel files.

spice-kernel-db scan <directory> [--mission NAME] [-v] [--archive]

Option	Description
`directory`	Root directory to scan recursively
`--mission`	Override auto-detected mission name
`-v, --verbose`	Print each registered file
`--archive`	Move files to the configured kernel directory and leave symlinks at the original locations

# Auto-detect mission from path structure
spice-kernel-db scan /data/spice/JUICE/kernels

# Explicit mission label
spice-kernel-db scan /data/spice/generic_kernels --mission generic

# Verbose output
spice-kernel-db scan /data/spice/MRO/kernels -v

# Import kernels from a random directory into the central archive
spice-kernel-db scan /tmp/downloaded_kernels --mission JUICE --archive

With --archive, each kernel file is moved into the configured kernel directory (organized as {kernel_dir}/{mission}/{type}/{filename}) and a symlink is left at the original location. This lets you import kernels from anywhere while keeping the original paths functional.

Note

Symlinks require filesystem support. On Windows, Developer Mode or administrator privileges are needed. If symlink creation fails, the file is still moved and registered — only the symlink is skipped (with a warning).

`stats`

Print database summary statistics.

spice-kernel-db stats

Shows unique kernels, total locations, total size, number of duplicates, registered missions, and a breakdown by kernel type.

`duplicates`

Report all duplicated kernels.

spice-kernel-db duplicates

Lists each kernel that exists in 2+ locations, showing all paths and missions, with a total wasted space calculation.

`check`

Check which kernels from a metakernel are available locally.

spice-kernel-db check [metakernel] [--mission NAME] [-v]

Option	Description
`metakernel`	Path to a `.tm` file or registry filename. Omit to select interactively from locally acquired metakernels.
`--mission`	Mission name for preferred-mission resolution
`-v, --verbose`	Show full per-file warnings instead of compact summary

# Interactive — pick from local metakernels
spice-kernel-db check

# Explicit metakernel
spice-kernel-db check juice_crema_5_1.tm --mission JUICE

# Full per-file warnings
spice-kernel-db check juice_crema_5_1.tm -v

Reports found/missing counts, lists missing files, and shows warnings for cross-mission fallbacks. By default, warnings are grouped into a compact summary (dedup resolutions, cross-mission lookups). Use -v to see full per-file details.

If the metakernel was fetched from a remote server, check also queries the server to see if a newer version is available and prints a notice if so. This adds one HTTP request but does not download anything.

`rewrite`

Rewrite a metakernel with a local symlink tree.

spice-kernel-db rewrite <metakernel> -o <output> [--link-root DIR] [--mission NAME]

Option	Description
`metakernel`	Path to original `.tm` file
`-o, --output`	Output `.tm` path (required)
`--link-root`	Root for symlink tree (default: `kernels/` next to output)
`--mission`	Mission name for preferred-mission resolution

# Basic usage
spice-kernel-db rewrite juice_crema_5_1.tm -o juice_local.tm

# Custom symlink root
spice-kernel-db rewrite juice_crema_5_1.tm -o juice_local.tm \
    --link-root /data/spice/unified

# Explicit mission
spice-kernel-db rewrite juice_crema_5_1.tm -o juice_local.tm --mission JUICE

`resolve`

Find the local path for a single kernel filename.

spice-kernel-db resolve <filename> [--mission NAME]

Option	Description
`filename`	Kernel filename to look up
`--mission`	Preferred mission for resolution

spice-kernel-db resolve naif0012.tls --mission JUICE
# /data/spice/JUICE/kernels/lsk/naif0012.tls

spice-kernel-db resolve mro_sc_2024.bc --mission JUICE
# /data/spice/MRO/kernels/ck/mro_sc_2024.bc
#   ⚠ mro_sc_2024.bc: not found in [JUICE] registry, using copy from [MRO]

Prints the resolved path to stdout and any warnings to stderr.

`dedup`

Replace duplicate kernel files with symlinks.

spice-kernel-db dedup [--execute]

Option	Description
`--execute`	Actually replace files (default: dry run)

# Preview (default, safe)
spice-kernel-db dedup

# Do it
spice-kernel-db dedup --execute

The canonical copy (the file that symlinks point to) is chosen with a preference for files in the generic mission.

`metakernels` (alias: `mk`)

List tracked metakernels or show detailed info about a specific one.

spice-kernel-db metakernels [name] [--mission NAME]
spice-kernel-db mk [name] [--mission NAME]

Option	Description
`name`	Optional: show info for a specific metakernel (by filename)
`--mission`	Filter listing by mission name

# List all tracked metakernels
spice-kernel-db metakernels

# Filter by mission
spice-kernel-db metakernels --mission JUICE

# Detailed info for a specific metakernel
spice-kernel-db metakernels juice_crema_5_1.tm

When no name is given, prints a summary table with kernel counts and availability. When a name is given, shows per-kernel status with type, size, and whether each kernel is in the database or missing.

`get`

Fetch a remote metakernel, show which kernels are needed, and download missing ones.

spice-kernel-db get <url> [--download-dir DIR] [--mission NAME] [-y]

Option	Description
`url`	URL to a remote `.tm` metakernel, or just a filename (e.g. `juice_ops.tm`)
`--download-dir`	Override default kernel storage directory
`--mission`	Override auto-detected mission name (required if multiple missions known and using filename)
`-y, --yes`	Skip confirmation prompt

# By filename (after browsing a mission at least once)
spice-kernel-db get juice_ops.tm

# By filename with explicit mission (when multiple missions are known)
spice-kernel-db get juice_ops.tm --mission JUICE

# By full URL
spice-kernel-db get https://naif.jpl.nasa.gov/pub/naif/JUICE/kernels/mk/juice_ops.tm

# Auto-confirm download
spice-kernel-db get juice_ops.tm -y

When a filename is given instead of a URL, the tool looks up the mk/ directory URL from the missions table (configured via mission add). Mission names support case-insensitive prefix matching (e.g. --mission bepi matches BEPICOLOMBO). If multiple missions are known, use --mission to disambiguate.

The tool fetches the remote metakernel, resolves each kernel entry to a full URL, checks your local database, queries remote file sizes (in parallel), and displays a summary table. Downloaded kernels are stored preserving the remote subdirectory structure (e.g. lsk/, spk/, ck/) and automatically registered in the database.

`update`

Re-fetch a metakernel from its source URL and download any new or missing kernels.

spice-kernel-db update [metakernel] [--mission NAME] [--download-dir DIR] [-y]

Option	Description
`metakernel`	Metakernel filename or path. Omit to select interactively.
`--mission`	Override mission name
`--download-dir`	Override default kernel storage directory
`-y, --yes`	Skip confirmation prompt

# Interactive selection
spice-kernel-db update

# By filename
spice-kernel-db update juice_ops.tm

# Auto-confirm
spice-kernel-db update juice_ops.tm -y

This is a convenience command that combines looking up the source URL from the metakernel registry and calling get. It’s the recommended action after check or browse reports that a remote update is available. Metakernels added via scan (without a source URL) cannot be updated this way — use get with an explicit URL instead.

`browse`

Browse remote metakernels in a NAIF mission mk/ directory, or list known directories.

spice-kernel-db browse [url] [--mission NAME]

Option	Description
`url`	URL to a mission’s `mk/` directory, or a mission name (omit to list known directories)
`--mission`	Override auto-detected mission name
`--show-versioned`	Show versioned snapshots under each metakernel

# List all known mk/ directories (from missions table and previously acquired metakernels)
spice-kernel-db browse

# Browse by mission name (prefix matching, case-insensitive)
spice-kernel-db browse JUICE
spice-kernel-db browse bepi    # matches BEPICOLOMBO

# Browse by full URL
spice-kernel-db browse https://naif.jpl.nasa.gov/pub/naif/JUICE/kernels/mk/

Without a URL, lists all remote mk/ directories known from the missions table and previous get commands, along with how many metakernels have been fetched from each:

Known remote metakernel directories:

  Mission  URL                                                        Acquired
  ───────  ─────────────────────────────────────────────────────────  ────────
  JUICE    https://naif.jpl.nasa.gov/pub/naif/JUICE/kernels/mk/            3
  MRO      https://naif.jpl.nasa.gov/pub/naif/MRO/kernels/mk/             1

Use 'spice-kernel-db browse <url>' to scan a specific directory.

With a URL, fetches the Apache directory listing, parses .tm file entries, groups them by base name (stripping version tags like _v461_20251127_001), and displays a compact summary:

Remote metakernels: JUICE (https://naif.jpl.nasa.gov/.../mk/)

  Metakernel                         Versions  Latest           Local
  ─────────────────────────────────  ────────  ──────────────── ────────
  juice_crema_5_0.tm                        1  2025-08-15 11:00 no
  juice_ops.tm                              3  2025-11-27 09:30 yes
  juice_plan.tm                             2  2026-02-02 14:00 outdated

  Total: 3 unique | 6 files | 1 locally acquired
  Run 'spice-kernel-db get <name>' to update outdated metakernels.
  Use --show-versioned to see individual snapshots.

The Local column shows three states:

yes — locally acquired and up to date (or scan-acquired, where remote date is unknown)
outdated — locally acquired but the remote copy has been modified since acquisition
no — not acquired locally

With --show-versioned, versioned snapshots are listed under each base metakernel:

  juice_ops.tm                                 2025-11-27 09:30    12K  yes
    snapshot: juice_ops_v230_20221128_001.tm   2022-11-28 10:00     8K
    snapshot: juice_ops_v461_20251127_001.tm   2025-11-27 09:30    12K

`coverage`

Check SPK body coverage in a metakernel. See the Coverage page for full details.

spice-kernel-db coverage <body> [metakernel] [--mission NAME]

Option	Description
`body`	NAIF body ID (e.g. `399`) or body name (e.g. `Earth`)
`metakernel`	Path to a `.tm` file or registry filename. Omit to select interactively.
`--mission`	Mission name for preferred-mission resolution

# Interactive — pick metakernel, resolve body name
spice-kernel-db coverage Earth

# Explicit
spice-kernel-db coverage 399 juice_ops.tm --mission JUICE

Requires the optional spiceypy dependency: pip install spice-kernel-db[spice]

`mission`

Configure missions for filename-based acquisition and browsing. Mission names are matched case-insensitively and support prefix matching — e.g. bepi matches BEPICOLOMBO, ju matches JUICE (as long as the prefix is unambiguous).

`mission add`

Interactively set up a new mission. The command guides you through:

Choose a server: [1] NASA [2] ESA
View available missions from that server
Select one by number or name
Configure deduplication: Enable deduplication for this mission? [Y/n]:
Store in database

spice-kernel-db mission add

After setup, the command prints next steps for acquiring metakernels.

`mission list`

Show all configured missions with their server, deduplication status, and mk/ directory URL.

spice-kernel-db mission list

Example output:

Configured missions:

  Mission  Server  Dedup  mk/ URL
  ───────  ──────  ─────  ──────────────────────────────
  JUICE    ESA     yes    https://spiftp.esac.esa.int/data/SPICE/JUICE/kernels/mk/
  MRO      NASA    no     https://naif.jpl.nasa.gov/pub/naif/MRO/kernels/mk/

`mission remove`

Remove a configured mission from the database.

spice-kernel-db mission remove <name>

Option	Description
`name`	Mission name to remove

spice-kernel-db mission remove MRO

`config`

Show or update configuration.

spice-kernel-db config [--setup]

Option	Description
`--setup`	Re-run the interactive first-time setup

# Show current settings
spice-kernel-db config

# Re-run setup (change database path, kernel directory, etc.)
spice-kernel-db config --setup

Without --setup, prints the current configuration: database path, kernel directory, and config file location.

`reset`

Delete the database and start fresh.

spice-kernel-db reset [-y]

Option	Description
`-y, --yes`	Skip confirmation prompt

# Interactive (asks for confirmation)
spice-kernel-db reset

# Skip confirmation
spice-kernel-db reset -y

Deletes only the DuckDB database file. Kernel files in the configured kernel directory are not touched. After resetting, you can re-index existing kernels:

spice-kernel-db scan ~/.local/share/spice-kernel-db/kernels

scan

stats

duplicates

check

rewrite

resolve

dedup

metakernels (alias: mk)

get

update

browse

coverage

mission

mission add

mission list

mission remove

config

reset

`scan`

`stats`

`duplicates`

`check`

`rewrite`

`resolve`

`dedup`

`metakernels` (alias: `mk`)

`get`

`update`

`browse`

`coverage`

`mission`

`mission add`

`mission list`

`mission remove`

`config`

`reset`