SI FabrikDocs
/
sifabrik.com ↗
Reference

harnessd CLI

Every harnessd command and option, with examples and exit behaviour.

TEXT
usage: harnessd <serve|check|user|audit> [args] --config <harnessd.yaml>
  serve                              run the server
  check                              validate configuration and security posture
  fingerprint                        print the TLS certificate's SHA-256 (to pin in the Mac app)
  user add <name> --role <role>      create an account (roles: admin, operator, viewer)
  user passwd <name>                 change a password (signs out the user's sessions)
  user totp <name> [--disable]       enroll (or remove) an authenticator app
  user disable|enable|remove <name>
  user list
  audit verify                       verify the audit log hash chain
  --password-stdin                   read the password from stdin instead of prompting

Global options#

OptionDescription
--config <path>The configuration file. Default: $HARNESSD_CONFIG, then /etc/harness/harnessd.yaml.

Every command loads the configuration, creates data_dir (mode 0700) if needed, and runs with a 0077 umask. Run commands as the harness user (sudo -u harness harnessd …) so files keep the right owner. Errors are printed to standard error as harnessd: <message>, with exit code 1.

serve#

Shell
harnessd serve --config /etc/harness/harnessd.yaml

Runs the security checks and refuses to start on any error (refusing to start: followed by the list). Then it removes leftover containers from an earlier run, loads and clones projects, starts those with auto_start, and serves the API on listen and the tools endpoint on tools_listen. It logs the certificate fingerprint at startup. SIGTERM and SIGINT shut down gracefully, stopping every orchestrator.

check#

Shell
harnessd check --config /etc/harness/harnessd.yaml

Validates the configuration and security posture, prints warning: and error: lines, then:

TEXT
ok: configuration passes security checks (3 project(s), 4 user(s))

or FAILED: N error(s) with exit code 1. See Security checks.

fingerprint#

Shell
harnessd fingerprint --config /etc/harness/harnessd.yaml

Prints the SHA-256 of the TLS certificate (the leaf, DER) as colon-separated hex. It's the value clients pin, and matches openssl x509 -noout -fingerprint -sha256 -in <cert>.

user#

CommandDescription
user add <name> --role admin|operator|viewerCreates an account. Prompts for the password twice, or reads one line with --password-stdin.
user passwd <name>Changes the password and signs out the user's sessions.
user totp <name>Enrolls an authenticator: prints an otpauth:// URI and the secret, then asks for the current code.
user totp <name> --disableRemoves the authenticator.
user disable <name> / user enable <name>Disables (signs out and blocks) or re-enables an account.
user remove <name>Deletes the account.
user listOne line per account: name, role, and disabled / totp flags, tab-separated.
Shell
sudo -u harness harnessd user add rob --role admin
sudo -u harness harnessd user totp rob
printf '%s\n' "$PW" | sudo -u harness harnessd user add ci --role viewer --password-stdin
sudo -u harness harnessd user list
# ci	viewer
# rob	admin	totp

Each user command is recorded in the audit log with the actor cli. Password rules: see Usernames and passwords.

audit verify#

Shell
harnessd audit verify --config /etc/harness/harnessd.yaml
# ok: 18342 record(s), hash chain intact

Recomputes the hash chain of data_dir/audit/audit.jsonl. On a break it prints audit chain broken at line N of M and exits 1.

See also#