CLI Reference

Complete reference for the blob command-line tool.

Global Flags

These flags apply to all commands:

Flag	Description	Default
`--config`	Path to config file	`~/.config/blob/config.yaml`
`--output`, `-o`	Output format: `table`, `json`, `plain`	`table`
`-v`, `--verbose`	Enable verbose output	false
`-q`, `--quiet`	Suppress non-essential output	false
`--no-color`	Disable colored output	false
`--plain-http`	Use HTTP instead of HTTPS for registries	false

Core Commands

blob push

Push a directory to an OCI registry as a blob archive.

Synopsis:

blob push [flags] <reference> <directory>

Arguments:

Argument	Description
`reference`	OCI reference with tag (e.g., `ghcr.io/org/repo:v1`)
`directory`	Source directory to archive

Flags:

Flag	Description	Default
`--compression`, `-c`	Compression: `none`, `zstd`	`none`
`--tag`, `-t`	Additional tags to apply (repeatable)
`--annotation`, `-a`	Add annotation `key=value` (repeatable)
`--max-files`	Maximum file count (0 = unlimited)	200000
`--sign`	Sign the archive after pushing	false

Examples:

# Basic push
blob push ghcr.io/myorg/archive:v1 ./src

# With compression
blob push --compression=zstd ghcr.io/myorg/archive:v1 ./src

# Multiple tags
blob push -t latest -t stable ghcr.io/myorg/archive:v1.0.0 ./src

# With annotations
blob push -a "org.opencontainers.image.source=https://github.com/myorg/repo" \
          ghcr.io/myorg/archive:v1 ./src

# Push and sign (keyless, requires OIDC environment)
blob push --sign ghcr.io/myorg/archive:v1 ./src

See Also: OCI Client - Push Operations

blob pull

Pull an archive from a registry and extract to a directory.

Synopsis:

blob pull [flags] <reference> <directory>

Arguments:

Argument	Description
`reference`	OCI reference (e.g., `ghcr.io/org/repo:v1`)
`directory`	Destination directory for extraction

Flags:

Flag	Description	Default
`--prefix`, `-p`	Extract only files under this prefix	`.` (all)
`--overwrite`	Overwrite existing files	false
`--preserve-mode`	Preserve file permission modes	false
`--preserve-times`	Preserve file modification times	false
`--clean`	Remove destination before extracting	false
`--workers`	Parallel extraction workers (0 = auto)	0
`--skip-cache`	Bypass all caches	false
`--verify`	Require signature verification	false
`--policy`	Path to verification policy file

Examples:

# Basic pull
blob pull ghcr.io/myorg/archive:v1 ./dest

# Extract specific directory
blob pull --prefix=config ghcr.io/myorg/archive:v1 ./dest

# With metadata preservation
blob pull --preserve-mode --preserve-times ghcr.io/myorg/archive:v1 ./dest

# Clean extraction (removes existing files)
blob pull --clean ghcr.io/myorg/archive:v1 ./dest

# With signature verification
blob pull --verify ghcr.io/myorg/archive:v1 ./dest

See Also: Extracting Files

blob cp

Copy specific files from an archive to a local directory.

Synopsis:

blob cp [flags] <source>... <directory>

Arguments:

Argument	Description
`source`	Archive file reference: `<ref>:<path>`
`directory`	Destination directory

Flags:

Flag	Description	Default
`--overwrite`	Overwrite existing files	false
`--preserve-mode`	Preserve file permission modes	false
`--preserve-times`	Preserve file modification times	false

Examples:

# Copy single file
blob cp ghcr.io/myorg/archive:v1:config.json ./local/

# Copy multiple files
blob cp ghcr.io/myorg/archive:v1:config.json \
        ghcr.io/myorg/archive:v1:src/main.go \
        ./local/

# With overwrite
blob cp --overwrite ghcr.io/myorg/archive:v1:config.json ./local/

blob cat

Print file contents to stdout.

Synopsis:

blob cat [flags] <reference> <path>

Arguments:

Argument	Description
`reference`	OCI reference
`path`	File path within the archive

Examples:

# Print file contents
blob cat ghcr.io/myorg/archive:v1 config.json

# Pipe to other commands
blob cat ghcr.io/myorg/archive:v1 data.json | jq '.items[]'

Inspection Commands

blob ls

List files in an archive.

Synopsis:

blob ls [flags] <reference> [prefix]

Arguments:

Argument	Description
`reference`	OCI reference
`prefix`	Optional path prefix to filter files

Flags:

Flag	Description	Default
`--long`, `-l`	Show detailed file information	false
`--human`, `-h`	Human-readable sizes	false
`--sort`	Sort by: `name`, `size`, `time`	`name`
`--reverse`, `-r`	Reverse sort order	false

Examples:

# List all files
blob ls ghcr.io/myorg/archive:v1

# List with details
blob ls -lh ghcr.io/myorg/archive:v1

# List specific directory
blob ls ghcr.io/myorg/archive:v1 src/

# Sort by size
blob ls -l --sort=size ghcr.io/myorg/archive:v1

blob tree

Display archive contents as a tree.

Synopsis:

blob tree [flags] <reference> [prefix]

Arguments:

Argument	Description
`reference`	OCI reference
`prefix`	Optional path prefix

Flags:

Flag	Description	Default
`--depth`, `-d`	Maximum tree depth (0 = unlimited)	0
`--dirs-only`	Show only directories	false

Examples:

# Full tree
blob tree ghcr.io/myorg/archive:v1

# Limited depth
blob tree -d 2 ghcr.io/myorg/archive:v1

# Specific subtree
blob tree ghcr.io/myorg/archive:v1 src/

blob inspect

Show archive metadata and statistics.

Synopsis:

blob inspect [flags] <reference>

Arguments:

Argument	Description
`reference`	OCI reference

Flags:

Flag	Description	Default
`--referrers`	List referrer artifacts (signatures, attestations)	false
`--skip-cache`	Bypass all caches	false

Examples:

# Basic inspection
blob inspect ghcr.io/myorg/archive:v1

# Include referrers (signatures, attestations)
blob inspect --referrers ghcr.io/myorg/archive:v1

Output (table format):

Digest:             sha256:abc123...
Created:            2024-01-15T10:30:00Z
Files:              42
Data blob size:     1.2 MB
Index blob size:    8.5 KB
Uncompressed size:  3.4 MB
Compression ratio:  0.35

Annotations:
  org.opencontainers.image.source  https://github.com/myorg/repo
  org.opencontainers.image.created 2024-01-15T10:30:00Z

See Also: OCI Client - Inspect Operations

blob open

Open interactive TUI file browser.

Synopsis:

blob open [flags] <reference>

Arguments:

Argument	Description
`reference`	OCI reference

Keyboard Shortcuts:

Key	Action
`j/k` or `↑/↓`	Navigate files
`Enter`	Open file / expand directory
`h` or `←`	Go to parent directory
`l` or `→`	Expand / preview
`/`	Search
`n/N`	Next / previous search result
`y`	Copy file path
`q`	Quit

Examples:

# Browse archive
blob open ghcr.io/myorg/archive:v1

Security Commands

blob sign

Sign an archive manifest with Sigstore.

Synopsis:

blob sign [flags] <reference>

Arguments:

Argument	Description
`reference`	OCI reference (must exist)

Flags:

Flag	Description	Default
`--key`	Path to private key PEM file	(keyless)
`--fulcio`	Fulcio server URL	`https://fulcio.sigstore.dev`
`--rekor`	Rekor transparency log URL	`https://rekor.sigstore.dev`
`--oidc-issuer`	OIDC issuer URL	(auto-detect)
`--oidc-token`	OIDC identity token	(ambient)

Examples:

# Keyless signing (GitHub Actions with OIDC)
blob sign ghcr.io/myorg/archive:v1

# With private key
blob sign --key private.pem ghcr.io/myorg/archive:v1

blob verify

Verify archive signature and attestations.

Synopsis:

blob verify [flags] <reference>

Arguments:

Argument	Description
`reference`	OCI reference

Flags:

Flag	Description	Default
`--policy`	Path to policy YAML file
`--issuer`	Required OIDC issuer
`--identity`	Required signer identity (subject)
`--repo`	GitHub repo for GitHub Actions policy (owner/repo)
`--branches`	Allowed branches (comma-separated, supports wildcards)
`--tags`	Allowed tags (comma-separated, supports wildcards)

Examples:

# Verify with GitHub Actions policy
blob verify --repo=myorg/myrepo ghcr.io/myorg/archive:v1

# Verify with branch/tag restrictions
blob verify --repo=myorg/myrepo --branches=main --tags="v*" \
    ghcr.io/myorg/archive:v1

# Verify with policy file
blob verify --policy=policy.yaml ghcr.io/myorg/archive:v1

# Verify with explicit identity
blob verify --issuer="https://token.actions.githubusercontent.com" \
            --identity="https://github.com/myorg/repo/.github/workflows/release.yml@refs/heads/main" \
            ghcr.io/myorg/archive:v1

Policy File Format:

# policy.yaml
signature:
  issuer: https://token.actions.githubusercontent.com
  subject_regex: "^https://github.com/myorg/.*"

provenance:
  builder: https://github.com/slsa-framework/slsa-github-generator
  source_repo: https://github.com/myorg/myrepo
  branches:
    - main
  tags:
    - "v*"

blob tag

Create or update a tag pointing to an existing manifest.

Synopsis:

blob tag [flags] <reference> <new-tag>

Arguments:

Argument	Description
`reference`	Source reference (tag or digest)
`new-tag`	New tag name

Examples:

# Tag v1.0.0 as latest
blob tag ghcr.io/myorg/archive:v1.0.0 latest

# Tag by digest
blob tag ghcr.io/myorg/archive@sha256:abc123... stable

Management Commands

blob alias

Manage registry aliases.

Synopsis:

blob alias <subcommand>

Subcommands:

blob alias add

blob alias add <name> <registry-prefix>

Examples:

blob alias add prod ghcr.io/myorg/production
blob alias add staging ghcr.io/myorg/staging

blob alias rm

blob alias rm <name>

blob alias list

blob alias list

Output:

NAME     REGISTRY PREFIX
prod     ghcr.io/myorg/production
staging  ghcr.io/myorg/staging

blob cache

Manage local caches.

Synopsis:

blob cache <subcommand>

Subcommands:

blob cache status

Show cache statistics.

blob cache status

Output:

CACHE     SIZE      MAX       ENTRIES
refs      1.2 KB    5 MB      15
manifests 45 KB     10 MB     12
indexes   2.1 MB    50 MB     8
content   89 MB     100 MB    1,247
blocks    12 MB     50 MB     892

blob cache clear

Clear caches.

blob cache clear [layer]

Arguments:

Argument	Description
`layer`	Optional: `refs`, `manifests`, `indexes`, `content`, `blocks`

Examples:

# Clear all caches
blob cache clear

# Clear only content cache
blob cache clear content

blob config

Manage configuration.

Synopsis:

blob config <subcommand>

Subcommands:

blob config show

Display current configuration.

blob config show

blob config get

Get a configuration value.

blob config get <key>

blob config set

Set a configuration value.

blob config set <key> <value>

Examples:

blob config set output json
blob config set cache.dir ~/.cache/blob
blob config set cache.ref_ttl 10m

blob version

Print version information.

Synopsis:

blob version [flags]

Flags:

Flag	Description
`--short`	Print version number only

Output:

blob version 1.0.0
  commit: abc1234
  built:  2024-01-15T10:30:00Z
  go:     go1.21.5

Configuration

Config File Format

The configuration file is located at ~/.config/blob/config.yaml (or $XDG_CONFIG_HOME/blob/config.yaml).

# Output format: table, json, plain
output: table

# Disable colored output
no_color: false

# Use HTTP for all registries
plain_http: false

# Cache configuration
cache:
  # Cache directory (empty = caching disabled)
  dir: ~/.cache/blob

  # Reference cache TTL
  ref_ttl: 5m

  # Cache size limits (bytes, supports K/M/G suffixes)
  content_max: 100M
  blocks_max: 50M
  refs_max: 5M
  manifests_max: 10M
  indexes_max: 50M

# Registry aliases
aliases:
  prod: ghcr.io/myorg/production
  staging: ghcr.io/myorg/staging

# Default verification policy
verify:
  enabled: false
  policy: ~/.config/blob/policy.yaml

Environment Variables

Variable	Description	Equivalent Flag
`BLOB_CONFIG`	Config file path	`--config`
`BLOB_OUTPUT`	Output format	`--output`
`BLOB_CACHE_DIR`	Cache directory	`cache.dir`
`BLOB_NO_COLOR`	Disable colors (any value)	`--no-color`
`BLOB_PLAIN_HTTP`	Use HTTP (any value)	`--plain-http`

Environment variables override config file values. Flags override both.

Exit Codes

Code	Meaning
0	Success
1	General error
2	Invalid arguments or usage
3	Archive not found
4	Authentication failed
5	Network error
6	Verification failed (signature or policy)
7	Hash mismatch (integrity error)

Global Flags​

Core Commands​

blob push​

blob pull​

blob cp​

blob cat​

Inspection Commands​

blob ls​

blob tree​

blob inspect​

blob open​

Security Commands​

blob sign​

blob verify​

blob tag​

Management Commands​

blob alias​

blob alias add​

blob alias rm​

blob alias list​

blob cache​

blob cache status​

blob cache clear​

blob config​

blob config show​

blob config get​

blob config set​

blob version​

Configuration​

Config File Format​

Environment Variables​

Exit Codes​

See Also​

Global Flags

Core Commands

blob push

blob pull

blob cp

blob cat

Inspection Commands

blob ls

blob tree

blob inspect

blob open

Security Commands

blob sign

blob verify

blob tag

Management Commands

blob alias

blob alias add

blob alias rm

blob alias list

blob cache

blob cache status

blob cache clear

blob config

blob config show

blob config get

blob config set

blob version

Configuration

Config File Format

Environment Variables

Exit Codes

See Also