CLI Reference

Author:

Rohit Goswami

Synopsis

bless [OPTIONS] -- COMMAND [ARGS...]
bless --serve ADDR
bless ls
bless show <id>
bless fetch <id> [-o PATH]

Options

--label <LABEL>

Label for the run. Used in the output filename and MongoDB metadata.

Default: default_label

--no-timestamp

Omit timestamps from stdout when --format=log (the default). JSONL stdout always includes ts. The gzip file still includes full timestamps.

Useful for piping --format=log output to downstream tools that expect clean lines.

--format <FORMAT>

Output format for stdout. Values:

  • log (default): [TIMESTAMP LEVEL] message

  • jsonl: {"ts":"...","level":"INFO","msg":"..."}

The gzip file always uses the log format regardless of this setting.

-o, --output <PATH>

Output file path. Defaults to {label}_{uuid}.log.gz in the current directory.

Special values:

  • -: skip file output entirely (stdout only)

Any other path is gzip-compressed, including names that do not end in .gz. There is no plain-text file backend.

--split

Write separate gzip files for stdout and stderr:

  • {label}_{uuid}_stdout.log.gz – INFO and TRACE

  • {label}_{uuid}_stderr.log.gz – WARN and ERROR

--split is ignored when -o - (stdout only, no gzip files). A custom -o path inserts _stdout / _stderr before the extension (build_log.gz becomes build_log_stdout.log.gz).

--version

Print version and exit.

Query subcommands

These inspect existing runs. They do not require -- or a wrapped command. <id> is a full run_uuid or a unique prefix. If the prefix matches more than one uuid, the command exits with an error.

ls

List gzip files in the current directory whose names look like {label}_{uuid}.log.gz or the split pair {label}_{uuid}_stdout.log.gz / {label}_{uuid}_stderr.log.gz.

Prints uuid, label, stream (or -), path, and size.

With --use-mongodb (requires --features mongodb), lists documents in bless.commands (or --db / --collection) and prints run_uuid, label, stream, storage, size_bytes, and start_time.

show <id>

Print the ls fields for matching files, plus the file mtime. Mongo show prints the Mongo ls columns for the matching documents.

fetch <id>

Copy the matching gzip.

  • Default destination: {uuid}.log.gz

  • Split run (two matches): {uuid}_stdout.log.gz and {uuid}_stderr.log.gz

  • -o PATH: write that single file; error if the id matches two streams

  • -o -: write gzip bytes to stdout; error if the id matches two streams

With --use-mongodb, downloads the stored gzip_blob or streams the GridFS object named by gzip_blob_id. Requires MONGODB_URI.

MongoDB options

Available when built with --features mongodb.

--use-mongodb

Store the gzip log blob in MongoDB after the command finishes.

Requires MONGODB_URI environment variable.

Uploads the gzip file(s) the logger actually opened. Cannot be combined with -o - (no file to persist; config error). Every document writes stream: empty string for a combined run, or "stdout" / "stderr" with --split (one document per stream, shared run_uuid). Unique compound index is (run_uuid, stream).

Without --split, that gzip is the full combined archive (TRACE, DEBUG, INFO, WARN, ERROR), same as a run without --use-mongodb. --split writes INFO and TRACE to the stdout gzip and WARN and ERROR to the stderr gzip.

Default destination is the commands collection in the bless database.

--db <NAME>

MongoDB database name. Default: bless. Also reads MONGODB_DB.

Has no effect unless --use-mongodb is also set.

--collection <NAME>

MongoDB collection name. Default: commands. Also reads MONGODB_COLLECTION.

Has no effect unless --use-mongodb is also set.

--force-gridfs

Upload the gzip blob via GridFS even when it fits in a BSON document.

Has no effect unless --use-mongodb is also set. Blobs larger than 15 MiB already use GridFS automatically.

Serve mode options

Available when built with --features serve.

--serve <ADDR>

Start in server mode, listening for capnp RPC connections. No wrapped command is required. Conflicts with --remote and --use-mongodb.

:port binds 127.0.0.1:port (not all interfaces). An explicit host is unchanged.

Example: --serve :5678

--remote <ADDR>

Stream logs to a remote bless server. The wrapped command is still required. :port connects to 127.0.0.1:port.

Without --local and without -o, no local gzip is written. An explicit -o still writes that path.

Example: --remote :5678

--local

Requires --remote. Also write a local gzip file (default {label}_{uuid}.log.gz unless -o is set).

Exit codes

bless passes through the exit code of the wrapped command. If the command exits with code 42, bless exits with code 42.

If bless itself fails (e.g., cannot create log file), it exits with code 1 and prints the error to stderr.