Skip to content
x-meshPublic

About

everyday carry for SE and SRE — a read-only network and system diagnostic CLI for Linux and macOS

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

English | 한국어

edc

edc is everyday carry for systems work: a terminal toolkit for SEs and SREs to inspect hosts, follow resource use, investigate failures, and run remote tasks.

Start with the host: info shows its configuration and current state, and top follows CPU, memory, disk, network, and processes. From there, inspect disk usage, check a connection, trace activity, or record what happened for later comparison. Linux and macOS share the CLI; individual commands have platform and privilege requirements.

Live resource and process dashboard rendered with synthetic demo data

The screen uses synthetic demo data with the current UI renderer. Reproduce the captures.

Task Start here Details
Inspect a host and its resource use edc info, edc top Host information, dashboard
Find what is broken now edc check, edc check --group <group> Health check, check routines
Find a file by name edc find, edc find nginxconf /etc Find files
Find where disk space goes edc du /var, edc clean Directory usage, known caches
Investigate a service or container edc svc, edc ctr Services, containers
Look into one process edc proc <pid|name> Process view
See scheduled jobs and their last result edc jobs Scheduled jobs
Check a connection edc dns lookup example.com, edc tcp check example.com:443 Network checks, combined diagnosis
Trace application and kernel activity edc trace Tracing and packet capture — support varies by trace
Record and compare runs edc top -w, edc history, edc log -- <command> Resource history, command logs
Work across hosts edc remote, edc clean --group <group> Remote recipes, remote disk survey

Inspection commands do not automatically repair the host. Explicit actions have effects: remote runs recipe commands, check <routine> runs the commands of a configured routine, watch fs --exec and --rules run configured actions, and route, disk, and change modify host settings. Recording, log rotation, pruning, setup, and updates also write or delete data. compress and decompress write files, and their --rm deletes the input. See each command's requirements before using it in automation.

Install · Quick start · Configuration · Build from source · Exit codes

Install

Linux and macOS releases include amd64 and arm64 binaries. The install script selects the binary and verifies its SHA-256 checksum.

curl -fsSL https://github.com/x-mesh/edc/releases/latest/download/install.sh | sh

Install paths, PATH setup, updates, and source builds →

Quick start

After installation, check the version and inspect the host without a public IP lookup:

edc version
edc info --public=false

info prints system, memory, network, disk, and process information. Open the live resource dashboard next:

edc top
Host information screen (synthetic demo data)

Host information screen (synthetic demo data)

Press q to exit. For bounded output or a script, collect five samples as JSON lines:

edc top --count 5 --json -

--json - writes JSON to stdout. --json report.json writes it to a file. If --json is the last argument or the next argument is another option, it also writes to stdout. An argument such as -report.json, which starts with - and has a . or a /, is a file name.

Use the task table above to choose the next command. edc help lists commands, and edc help top shows a command's options. Source builds use ./bin/edc in place of edc.

Host inspection

Inspect configuration, memory, disks, and listening ports with info. On Linux and macOS, check looks for failed services, defunct processes, full disks, memory kills, and other current problems in one run. On Linux, inspect systemd services, recent changes, and kernel events. On Linux and macOS, inspect Docker containers through a Unix socket.

edc info --public=false
edc check
edc svc
edc ctr
edc changes --since 2h

Host information, health check, service and container views, audit, and events →

By default, edc ctr uses Docker Engine API data only. See the container guide for the optional local Linux collector.

Live monitoring

Follow host resources and the busiest processes in top. Switch views to inspect CPU, memory, disk, or network activity; use process filters to focus on a service. ai shows local Claude Code and Codex token usage and account limits. ai sessions shows which sessions need you, and ai agents shows the Claude Code sessions, subagents, and background shells that run now.

edc top --process postgres
edc ai

Dashboard controls, process filters, and AI usage →

Disk usage

du quickly finds where disk space goes. It scans directories with 4 workers by default and lets you explore the largest entries first.

clean is a read-only disk survey. It does not delete files. It measures known caches and other candidates and shows cleanup commands when requested; you choose whether to run them.

Directory browser showing disk usage, rendered from synthetic demo data

edc du /var
edc clean

The screen uses synthetic demo data. Both commands support Linux and macOS; some filesystem and Docker details are platform specific.

compress and decompress make an old log smaller on a host without zstd or pigz. They write .gz or .zst on several cores. They keep the input unless you add --rm, and they do not overwrite a file. See Compress and decompress files.

Disk usage and cache inspection details →

Record and compare

Record resource observations, browse earlier runs, and compare metrics over time. Snapshots and saved reports help compare host state; log keeps command output and execution history.

Daily CPU trend browser rendered from synthetic demo data

edc top -w
edc history trend
edc log -- ls -lh

Stop top with q, then open history trend to inspect the recording. The screen illustrates a multi-day history with synthetic data; a new recording starts with the samples you collect.

Recording, trends, growth, and command history details →

Tracing and packet capture

Follow application requests and kernel activity to investigate a failure. HTTP trace shows request paths, response status, and measured latency; press i to preview a message below the event list.

HTTP requests and responses with a message preview

Screen rendered with synthetic demo data. HTTP trace requires Linux 5.15 or later with eBPF privileges, or macOS with packet capture privileges. On a host with the required capabilities, trace a local HTTP service on port 8080:

sudo edc trace http --side server --port 8080

Press Ctrl-C to stop collection and print the summary. Trace support varies by OS, kernel, and protocol.

HTTP tracing details → · All traces and packet capture →

Remote tasks

Use inventory groups and recipes to plan work across hosts, execute steps, and verify results. OpenSSH supplies connection settings. Recipes execute the commands you configure.

Remote recipe plan using an example inventory without SSH connections

edc remote --list
edc remote --dry-run --group <group> --recipe <recipe.yaml>

Configure an inventory and recipe before running these examples. The demo shows a plan using example files; it makes no SSH connections. --dry-run displays planned work without executing recipe commands.

Inventory, recipes, execution, and SSH tunnels →

Network checks

Check a specific layer, or use doctor for a combined diagnosis:

edc dns lookup example.com
edc tcp check example.com:443
edc tcp scan --ports 22,80,443 example.com
edc doctor https://example.com

DNS, TCP, TLS, HTTP, doctor, quality, and file watching details →

File watching and actions (Linux and macOS)

Watch a directory and run a command when a file changes:

edc watch fs ./src -r --event create,modify --match '**/*.go' --exec 'go test ./...'
edc watch fs --rules watch.yaml --dry-run

--rules reads the rules from a YAML file. To keep the watch active after logout, run it as a systemd service.

File watching, rules files, and service setup →

Protected host changes

On Linux, explicitly manage routes, grow disks, or apply protected access changes with rollback. Review the privilege, confirmation, and recovery requirements before applying a change.

For a route switch with an active rollback timer:

flowchart LR
    A["Save current route<br/>Arm rollback timer"] --> B["Switch exit"]
    B --> C{"Verify and confirm"}
    C -->|"Confirmed"| D["Disarm timer<br/>Keep new route"]
    C -->|"Failure or cancel"| E["Restore saved route"]
    A -. "Timer expires without confirmation" .-> E
Loading

Route switching, protected changes, and disk growth →

Guides

Guide Contents
Installation and configuration Installation, updates, build, language, defaults, completion
Host inspection Host information, health check, services, containers, audit, changes, events
Live resource monitoring Top controls, thresholds, processes, AI usage
Network checks DNS, TCP, TLS, HTTP, doctor, location, file watching
Disk usage and known caches Directory browser, caches, Docker, worktrees, remote surveys
Recordings, history, and reports Recordings, snapshots, trends, growth, reports, command logs
Remote tasks and SSH tunnels Inventory, recipes, execution plans, SSH tunnels
Protected host changes Routes, rollback, disk growth
Tracing and packet capture Application protocols, kernel traces, payloads, PCAP

Exit code

  • 0: success, or warnings only
  • 1: one or more probes fail, or report diff finds a worse probe
  • 2: a run error, such as an argument, a config, a log start, or a report parse error
  • 3: not enough privilege for a privileged task
  • 4: user cancel, which includes a cancelled selection and Ctrl-C in remote and doctor
  • 124: the final log attempt exceeds its timeout

Current scope

Capability Platforms
Host resources, directory usage, cache inspection, network probes Linux and macOS
Host audit Linux and macOS (macOS: some checks)
systemd, recent host changes and kernel events Linux
Application and kernel tracing Varies by trace, kernel, and privileges
Remote recipes Uses local OpenSSH; remote commands depend on each host

Platform requirements and external lookups · Trace requirements · Configuration and language

License

MIT. See LICENSE.

About

everyday carry for SE and SRE — a read-only network and system diagnostic CLI for Linux and macOS

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages