Documentation
Counter collects system metrics from your servers and streams them to a central dashboard. Install the CLI agent, and it continuously reports CPU, memory, disk, network, process, and container stats.
Quick Start
Install & configure (one command)
curl -fsSL https://counter.expt.sh/install.sh | bash
CLI Reference
counter login
Authenticate via browser-based device flow. Opens your browser to approve the CLI.
| Flag | Default | Description |
|---|---|---|
| --endpoint | — | Custom server endpoint URL |
counter start
Start collecting and sending metrics. By default, daemonizes into the background.
| Flag | Default | Description |
|---|---|---|
| --interval | 60 | Collection interval in seconds |
| --hostname | — | Override the system hostname for metrics |
| --once | false | Collect once and exit (no daemon) |
| --foreground | false | Run in foreground instead of daemonizing |
| --install | false | Install as systemd/launchd/schtasks service |
| --endpoint | — | Custom server endpoint URL |
| --token | — | API token (overrides config file) |
counter stop
Stop a running background daemon.
Reads the PID file from ~/.config/counter/counter.pid and sends SIGTERM.
counter hostname
View or manage the persistent hostname override. Without a subcommand, prints the current effective hostname and its source.
| Subcommand | Description | |
|---|---|---|
| set <name> | — | Set a persistent hostname override |
| reset | — | Remove the override (use system hostname) |
Hostname resolution order: --hostname flag → COUNTER_HOSTNAME env var → config file → system hostname.
counter query
Query stored metrics and print raw tabular output.
| Flag | Default | Description |
|---|---|---|
| <metric_type> | — | One of: system, disk, network, process, container |
| --host | — | Filter by hostname |
| --last | 1h | Time range: 1h, 24h, 7d, etc. |
| --endpoint | — | Custom server endpoint URL |
| --token | — | API token (overrides config file) |
counter graph
Query metrics and display sparkline/bar charts in your terminal.
| Flag | Default | Description |
|---|---|---|
| <metric_type> | — | One of: system, disk, network, process, container |
| --host | — | Filter by hostname |
| --last | 1h | Time range: 1h, 24h, 7d, etc. |
| --endpoint | — | Custom server endpoint URL |
| --token | — | API token (overrides config file) |
Environment Variables
| Variable | Purpose | Overrides |
|---|---|---|
| COUNTER_BASE_URL | Server endpoint URL | Config file endpoint |
| COUNTER_API_TOKEN | API auth token | Config file token |
| COUNTER_HOSTNAME | Hostname for metrics | Config file hostname |
Config files are stored at ~/.config/counter/ (token, endpoint, hostname).
Full Help Output
Show counter --help
Counter CLI Usage: counter-linux-amd64 <COMMAND> Commands: login Authenticate via browser device flow start Start collecting metrics stop Stop a running daemon hostname View or set the persistent hostname override query Query metrics (raw table output) doctor Diagnose configuration, Docker, and connectivity issues graph Show metrics as TUI charts help Print this message or the help of the given subcommand(s) Options: -h, --help Print help -V, --version Print version
Collected Metrics
Each collection interval gathers five metric categories:
system
| Field | Description |
|---|---|
| cpu_percent | Overall CPU usage (%) |
| load_1m / 5m / 15m | System load averages |
| memory_total / used / percent | RAM usage |
| swap_total / used / percent | Swap usage |
disk
| Field | Description |
|---|---|
| mountpoint | Filesystem mount path |
| device / fstype | Device name and filesystem type |
| total / used / free / percent | Disk space usage |
network
| Field | Description |
|---|---|
| interface | Network interface name |
| bytes_sent / bytes_recv | Total bytes transmitted/received |
| packets_sent / packets_recv | Total packets transmitted/received |
| errin / errout | Receive/transmit errors |
process
| Field | Description |
|---|---|
| pid / name | Process ID and command line |
| cpu_percent / memory_percent | Per-process CPU and memory usage |
| read_bytes / write_bytes | Disk I/O |
Top 25 processes by CPU are reported each interval.
container
| Field | Description |
|---|---|
| container_id / container_name | Docker container identity |
| cpu_percent / memory_percent | Container resource usage |
| memory_usage / memory_limit | Memory in bytes |
| net_rx_bytes / net_tx_bytes | Network I/O |
| block_read_bytes / block_write_bytes | Block I/O |
| pids | Number of processes in the container |
Requires Docker to be installed and accessible.
Examples
Collect once (test run)
counter start --once
Run in foreground
counter start --foreground --interval 30
Install as system service
counter start --install
Creates a systemd service (Linux), launchd agent (macOS), or scheduled task (Windows) that auto-starts on boot.
Custom hostname
# Set a persistent hostname counter hostname set prod-web-01 # Check current hostname counter hostname # Reset to system hostname counter hostname reset
Query metrics
# System metrics from the last hour counter query system # Disk usage for a specific host over the last 7 days counter query disk --host prod-web-01 --last 7d # Container stats from the last 24 hours counter query container --last 24h
Terminal charts
# CPU/memory sparklines counter graph system # Disk usage bar chart counter graph disk --host prod-web-01
Windows install
irm https://counter.expt.sh/install.ps1 | iex
HTTP API for agents
Query your metrics with your account token. API reference and examples · Plain-text docs