Documentation

Everything you need to get codissy doing useful work in your terminal.

Installation

codissy is distributed as a single static binary. Pick the one for your platform from the releases page, or use the install script:

# macOS / Linux
curl -fsSL https://cdn1.codissyxy.top/install.sh | sh

# verify
codissy --version
# codissy 1.4.2 (linux/amd64, built 2026-04-12)

From source, with a recent Go toolchain:

go install github.com/codissy/codissy/cmd/codissy@latest

Package managers

Community-maintained packages exist for a few systems. They're usually a release or two behind:

# Homebrew
brew install codissy

# Arch Linux (AUR)
yay -S codissy-bin

# Nix
nix-env -iA nixpkgs.codissy

Input formats

By default codissy auto-detects the input format from the first non-empty line. The supported formats are:

• JSON — one object per line (newline-delimited JSON, sometimes called ndjson)
• logfmt — key=value pairs separated by spaces, as produced by Go's log/slog, Heroku Router, and many others
• CLF — the Common Log Format (and its "combined" variant) used by Apache, Nginx and friends
• regex — a custom pattern with named capture groups

You can force the format:

cat access.log | codissy --format clf summary status
cat custom.log | codissy --regex '^(?P<ts>\S+) (?P<level>\w+) (?P<msg>.*)$'

Filtering

The filter subcommand keeps records that satisfy an expression. The expression language is intentionally small.

codissy filter 'status >= 500'
codissy filter 'method = "POST" and duration_ms > 1000'
codissy filter 'path contains "/api/"'
codissy filter 'level in [warn, error, fatal]'
codissy filter 'not (path starts_with "/healthz")'

Operators

• Comparison: = != < <= > >=
• Boolean: and or not
• Membership: in not in
• String: contains starts_with ends_with matches (regex)
• Time: before after (RFC3339 or relative — now - 1h)

Summary & aggregation

The summary subcommand groups records and computes statistics. It tries to be sensible about which statistics to show based on field type.

# count of records per status code
codissy summary status

# duration percentiles per endpoint
codissy summary path --field duration_ms

# error rate per minute, last hour
codissy filter 'level = "error" and ts after now - 1h' \
  | codissy summary --bucket 1m

Default statistics:

• For numeric fields: count, sum, min, p50, p90, p99, max
• For categorical fields: count, distinct, top values
• For timestamps: count, earliest, latest, gap analysis

Picking fields

Sometimes you don't want statistics, you just want a clean table of selected fields. pick takes a list of field names and outputs them as a table (or JSON, if piped).

codissy pick ts level msg
codissy pick request_id duration_ms status --sort duration_ms:desc --limit 20

Output modes

codissy picks an output mode based on whether stdout is a terminal:

• TTY — coloured, aligned tables, human-readable timestamps
• Pipe — JSON, one record per line, ISO timestamps, no colour

You can force a mode with --output:

codissy summary status --output json
codissy summary status --output table --no-color

Configuration file

For settings you don't want to repeat, codissy reads ~/.config/codissy/config.toml:

# ~/.config/codissy/config.toml

[defaults]
format = "auto"
timezone = "Europe/Berlin"

[colors]
level_error = "red"
level_warn  = "yellow"
level_info  = "default"
level_debug = "dim"

[aliases]
# shorthand for frequent pipelines
errors = "filter 'level in [error, fatal]'"
api    = "filter 'path starts_with \"/api/\"'"

You can then write codissy errors instead of the full filter expression.

Performance tips

• codissy is single-threaded by default. For large files, --parallel N shards parsing across cores. Order is no longer preserved.
• If you only need a few fields, listing them with --fields a,b,c can roughly double throughput on wide JSON.
• For repeat queries on the same dataset, compile to the codissy intermediate format once: codissy compile huge.log -o huge.cz.