Skip to main content

Command Tour

A tour of the commands you will use day to day, each with a real run and its output. Getting Started covers your first query; this page goes further. Every flag is listed in the CLI reference.

The examples run in a git repository at ~/proj, on a branch feature/login with uncommitted changes.

Read a value: comb get​

comb get <key> prints one value. A key is namespace.field: git is the namespace, branch the field. Every command has a one-letter short form, so comb g is comb get.

$ comb g git.branch
feature/login

A read of a value nothing has computed yet runs whatever provides it and waits for the answer, so the first read of a key can take a moment; later reads come from the cache.

A whole namespace​

Leave off the field to read every field in the namespace, one field=value line each:

$ comb g hostname
name=laptop.local
short=laptop

Several keys in one call print one line each, in order:

$ comb g git.branch git.dirty battery.percent
feature/login
true
80

A key nothing answers prints nothing and exits 0. Add --strict to make that exit 1, for scripts that need to tell "empty" from "missing".

Which directory​

Some namespaces answer for a directory (git answers for the repository around it); others are the same everywhere (hostname, battery). A read addresses the current directory unless you say otherwise:

You writeIt reads
comb g git.branchthe current directory
comb g git.branch .the current directory, spelled out
comb g git.branch ~/projanother directory: a last argument starting with /, ~ or .
comb g git.branch -p ~/projthe same, as a flag
comb g myapp.status --globalthe global entry, ~, ignoring where you are
$ cd ~
$ comb g git.branch
$ comb g git.branch ~/proj
feature/login

The first read prints nothing: ~ is not in a repository. Values cascade from a directory up to ~; see The Cascade.

Output formats​

Text is the default, made for $(…) in a shell. -f picks another format, and a suffix on the command is its short spelling: comb g.j is comb g -f json.

$ comb g -f json git.ahead
1
$ comb g.j git.ahead git.branch hostname.short
[
1,
"feature/login",
"laptop"
]
$ comb g.s git.branch git.dirty
branch='feature/login'
dirty='true'

json keeps types (a number stays a number) and prints null for a miss. sh writes quoted assignments you can eval "$(comb g.s git)". There are also csv/CSV and tsv/TSV (uppercase adds a header row):

$ comb g.T hostname
name short
laptop.local laptop

A template​

Anything passed to -f that holds {{ or {% is a template. Reading a namespace binds its fields by name:

$ comb g -f '{{ branch }}{% if dirty %}*{% endif %}' git
feature/login*
$ comb g.f '{{ branch }} +{{ ahead }}' git
feature/login +1

The template language is explained in Templates.

See what is cached: comb status​

comb status (comb s) shows the cache as a table, one row per field, holding the values a read from this directory would answer. This excerpt is from the repository, after a prompt had read git, hostname and aws:

$ comb s
PROVIDER FIELD SOURCE VALUE PATH AGE POLL TTL
aws profile rendered ▸ default ~/proj - - ---
git ahead source(status) 1 ~/proj 13s×0 45s ★ 60s×02 (2m) ∙
git branch source(head) feature/login ~/proj 14s - ★ ∙
hostname short source(host) laptop ~ 13s×0 9m46s ★ 600s×06 (1h)
ColumnMeaning
PROVIDER, FIELDThe key: git and branch are git.branch
SOURCEWhat produced the value: a provider's Source (source(head)), put for stored data, or rendered for a template your shell rendered just now (marked ▸)
PATHThe directory the value belongs to; ~ for a global value
AGETime since the value was computed; ×0 is how many polls have run since anyone last read it
POLLTime until the next poll
TTL★ while the value is being read; a number counts down the idle steps left before eviction. 60s×02 is the poll rate and count, (2m) the time to eviction, ∙ that it watches files

comb status --help prints the same legend. Filter with --filter key=value (repeatable; != negates):

$ comb s --filter provider=git --filter field=branch
PROVIDER FIELD SOURCE VALUE PATH AGE POLL TTL
git branch source(head) feature/login ~/proj 25s - ★ ∙
$ comb s --filter value=main
PROVIDER FIELD SOURCE VALUE PATH AGE POLL TTL
git branch_default source(branches) main ~/proj 24s - ★ ∙
git branch_parent source(branches) main ~/proj 24s - ★ ∙

-a shows every row, including facets and absent values; --tree shows the layers behind each value; -f json or -f tsv give machine-readable rows. See comb s.

Follow a value: comb watch​

comb watch (comb w) prints a value now, then a new line each time it changes, until you press Ctrl-C:

$ comb w git.branch
feature/login
fix/typo

The second line appeared when another shell ran git switch -c fix/typo. It takes the same formats as get; comb w.j prints one compact JSON document per change.

Combine values: comb eval​

comb eval (comb e) renders a template over any keys, all fetched in one request:

$ comb e '{{ git.branch }}{% if git.dirty %}*{% endif %} on {{ hostname.short }}'
feature/login* on laptop
$ comb e '{{ env.USER }} up {{ uptime.days }}d'
jane up 52d

A template that is a single {{ … }} keeps its value's type, which -f json shows:

$ comb e '{{ git.ahead + git.behind }}'
1
$ comb e.j '{{ git.dirty }}'
true

Store your own values: comb put​

comb put (comb p) stores JSON under a key, so a script can publish state for your prompt or status bar to read. It prints nothing on success.

$ comb p deploy '{"status":"passing","build":412}'
$ comb g deploy
build=412
status=passing

A put applies to its directory and every directory below it, and --global stores one value for everywhere:

$ cd ~/proj/src
$ comb g deploy.status
passing

A put replaces what it addresses. Put a field to change only that field; put the namespace to replace all of it:

$ comb p deploy.status '"failing"'
$ comb g deploy
build=412
status=failing

null removes a value:

$ comb p deploy null
$ comb g.j deploy
null

--ttl makes a value expire: it lives for the ttl, lingers for one idle step, and is then removed. Putting it again renews it:

$ comb p --global build.eta '"4m"' --ttl 30s
$ comb g build.eta
4m

See comb p.

Get a fresh value: refresh, --force, --wait​

Providers keep themselves current by watching files and polling, so you rarely need these. They are for when you know something changed that the provider cannot see.

CommandUse it when
comb r gitA hook or script should recompute a value, and needs no answer. comb r git.commit reruns only the Source that owns commit
comb g --force git.lines_addedYou want the recomputed value back now
comb g --wait forever git.commitYou want a read to wait for a run in progress, however long it takes
comb g --wait 0 git.commitYou want whatever is stored, at once, even if stale
$ comb r git
$ comb g --force git.lines_added
1

refresh prints nothing on success. A namespace you made with put has nothing to recompute:

$ comb r deploy
error: deploy: nothing to refresh: deploy has no sources

Check health: comb check​

comb check (comb c) runs health checks and prints [PASS], [WARN] or [FAIL] for each. With no subcommand it runs all of them; name one to narrow it:

$ comb c daemon
Daemon
[PASS] beachcomber 0.9.1 — pid 42062 — uptime 1m37s
[PASS] socket /tmp/beachcomber-501/sock
[INFO] config no config.toml
[PASS] requests_total=308 in_flight=0 active_watchers=0 cache_entries=29
[PASS] daemon responsive
[PASS] in_flight=0
[PASS] watch backend: native fs events
[PASS] reaper: not armed (side daemon)

comb c config validates your configuration, and comb c config --origins <key> shows which file set a setting:

$ comb c config --origins daemon.providers.git.sources.diff.return
KEY SOURCE VALUE
daemon.providers.git.sources.diff.return config(~/.config/beachcomber/defaults/git.toml) {{ result | watch('.', '!.git') | poll('30s', 4) | failback('60s', 3) | budget('100ms') | nearest }}

It exits 0 when healthy, 1 on a warning and 2 on a failure. The other subjects (providers, cache, watches, timers, …) are listed under comb c.

Stop the daemon: comb kill​

The daemon starts on the first comb command and stops itself when idle. comb kill (comb k) stops it now, for instance after upgrading comb; the next command starts a fresh one.

$ comb k
Daemon stopped (pid 42062).
$ comb k
Daemon is not running.

Next​