fid/README.md

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 (mode 0600) 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).