fid — command-line client
A dependency-free Go CLI for the fid REST API. One package, standard library only.
Build
go build -o fid .
Cross-compile for another platform/arch with GOOS/GOARCH, e.g.:
GOOS=darwin GOARCH=arm64 go build -o fid-mac .
GOOS=windows GOARCH=amd64 go build -o fid.exe .
./build.sh cross-compiles release binaries for the usual platforms
(linux/darwin/windows × amd64/arm64) into bin/, named fid-<goos>-<goarch>
(.exe added on windows), plus a bin/fid symlink to the one for the host
you're building on. Each run auto-increments the patch version kept in
version.txt and embeds it into every binary so fid version reports it;
name a version outright for a minor/major bump:
./build.sh # bump patch: 0.1.4 -> 0.1.5
VERSION=1.0.0 ./build.sh # set it explicitly
PLATFORMS="linux/amd64" ./build.sh # just one platform
Uploading the resulting bin/fid-* files as-is to a Gitea release tagged
with the bare version number (e.g. 0.1.5) is what fid -update expects to
find - see Updating below.
Usage
fid version print the fid version
fid login [user] log in (LDAP), stores a token in ~/.config/fid/config.json
fid logout forget the stored token
fid whoami show configured server / logged-in user / token status
fid server [url] show or set the configured server URL
fid renew manually renew the current token
fid list table of active devices (id, name, ip, mac, description, vlan, os, ...)
fid get <id>[,<id>...] show device record(s)
fid search <key> table of matching devices (same as the web UI's search box)
fid types list device types
fid departments list departments
fid fields list device field metadata (name/type/mandatory)
fid new key=value [...] create a device (e.g. fid new f_name=host1 l_dep=1 f_os=Linux f_contact=Mike)
fid new create a device in an interactive full-screen form (Linux/macOS)
fid edit <id> key=value [...] edit a device (partial update)
fid edit <id> edit a device in an interactive full-screen form (Linux/macOS)
fid delete <id> soft-delete a device
fid recover <id> undelete a device
fid -update download and install the newest release, replacing this binary
fid -check-update check whether a newer release is available, without installing it
fid list/fid search open an interactive, navigable table on a real
terminal — ↑/↓ to select a row, enter to jump straight into the
interactive edit form for that device, q/esc to quit. Piped or redirected
output (or -json) gets the plain table instead, unchanged.
Global flags (may appear anywhere in the args): -json for raw JSON output,
-server=URL to hit a different server for just one call, -insecure (or
$FID_INSECURE=1) to skip TLS certificate verification — only as a stopgap
on hosts with an outdated CA trust store.
Output is colored (using the palette from
mwxcol) when stdout/stderr is a real
terminal. Disable it with -no-color, or the $NO_COLOR /
$FID_NO_COLOR environment variables.
Example session:
$ fid login mike
password: ********
logged in as mike on https://fid.fhi.mpg.de
$ fid list
ID NAME IP MAC DESCRIPTION VLAN OS CONTACT
------ -------------------- --------------- ----------------- --------------------------- ------ ---------- ----------------
19 twilightzone 141.14.142.157 00:25:00:f0:bf:e8 TimeMachine Server PP&B FHI MacOS S.Pokrzykowski
21 ppb-copy 141.14.130.48 78:8c:77:56:c8:57 Lexmark CX963se FHI Lexmark OS PP&B 3456
...
$ fid search buntfink
40
$ fid get 40
id: 40
Name: buntfink
...
$ fid edit 40 f_comment="replaced toner"
updated device 40
list's table adapts to the terminal width (via $COLUMNS or stty size):
columns are shown in priority order — id, name, ip, mac, description, vlan,
os, contact, type, department, building, room, comment — for as many as fit,
and the name/description/comment columns stretch to use any leftover space.
Use fid -json list if you want the full, unfiltered list of ids instead.
fid new/fid edit <id> with no key=value arguments open a full-screen
form instead: ↑/↓ to move between fields, ←/→ to edit text / cycle a
select field's options, space to toggle a checkbox, Ctrl+S to save,
Esc to cancel. A failed save (e.g. a mandatory field left blank) shows the
server's error inline without losing what you typed. Needs a real terminal
(puts the tty in raw mode via stty), so it's Linux/macOS only — on Windows,
or when there's no tty, it prints an error telling you to use key=value
arguments instead.
Updating
fid checks https://git.fhi.mpg.de/mike/fid once a day in the background
(only when run interactively, on a real terminal) for a newer release, and
prints a one-line hint when it finds one - this costs nothing on the runs in
between, since it's just reading a cached note. fid -update downloads the
matching fid-<goos>-<goarch> asset from the latest release, runs it once
with -v to make sure it's not truncated or built for the wrong platform,
then replaces the running binary with it. fid -check-update reports what's
available without installing anything. Set $FID_NO_UPDATE_CHECK to turn off
the background check entirely.
Notes
- The token is stored in
~/.config/fid/config.json(mode0600) and is auto-renewed by the CLI whenever it has less than an hour left, so you normally only need to log in once a day. - Server defaults to
https://fid.fhi.mpg.de; override via$FID_SERVER,fid server <url>(persisted), or-server=<url>(one-off). - Password entry disables terminal echo (via
stty) when stdin is a tty; falls back to plain read otherwise (e.g. when scripted/piped).