CLI¶
The Hodeitek/hodeishield-cli repository
(Apache-2.0 license) publishes hodeishield, the official command-line client for
HodeiShield. The latest release has
binaries for Linux, macOS and Windows.
0.x
The CLI is at version 0.x: commands and output may still change before 1.0. The version that applies to you is always on the releases page. Portfolio access for an MSSP (see Several tenants (MSSP)) needs 0.4.0 or later.
Known limitation: macOS and Windows may block the binary
The macOS binary is not yet signed with an Apple Developer ID or notarized, so Gatekeeper may refuse to open a copy downloaded with a browser; the repository README explains what to do under If macOS or Windows blocks the binary, and the CLI issue hodeishield-cli#16 is still open. Verify the signature first (see below): it is the proof that the file is genuine.
On macOS, after the first blocked run, open System Settings › Privacy & Security, scroll
down to the message about hodeishield, click Open Anyway, confirm, and run the command
again. The dialog's wording and button labels follow the macOS language, so they may differ
from the English text here. The alternative, only once the signature or checksum has been
verified, is to remove the quarantine attribute from the unpacked binary:
xattr -d com.apple.quarantine ./hodeishield ("No such xattr" means there was nothing to
remove). A browser download sets that attribute and unpacking the archive with tar in
Terminal keeps it on the binary, so the block still applies; a download with curl does not
set it.
Support period
Each MAJOR version of the CLI is supported for 5 years, counted from 1.0.0. The 0.x series is pre-1.0: security fixes are delivered in the latest 0.x release. End of support is announced 12 months in advance. Security updates remain available after a subscription lapses; new features require an active subscription.
Plan
Access is part of your HodeiShield license. The MCP server requires the Operate or Enterprise plan instead. While your organization is in the HodeiShield beta, the CLI and the MCP server are included with the beta's full access.
It reads your third-party inventory, supply-chain alerts, risk register, compliance
posture, evidence and endpoint agents — the same public /v1 API the
MCP server consumes.
- Read-only. Every command is a
GETagainst/v1. Nothing here can change data in your organisation. - One tenant, or all your clients. A key or a sign-in covers one tenant; an MSSP reads its clients with one portfolio key, see Several tenants (MSSP).
- Safe with credentials. Sign-in tokens live in the system keychain by default; a plain-text token file exists only if you explicitly opt in on a machine without a keychain; nothing is ever printed or logged; credentials only travel over HTTPS and are never replayed to a redirect.
- Built for scripts.
--jsonprints the API's own JSON, exit codes say what went wrong, andHODEISHIELD_API_KEYworks without any interactive step. - Verifiable. Every release is signed with Sigstore (keyless, from GitHub Actions) and carries SLSA build provenance.
Install and verify¶
Installation methods change from release to release, so they are not repeated here: follow
the Install and Verify a download sections of the
repository README and download from the
latest release. Every release
carries a Sigstore signature, SLSA provenance and a software bill of materials (SBOM) for each
artifact, and the README shows the exact commands to check them for the version you
downloaded. Check the signature before you put hodeishield on your PATH.
The README offers these ways to install it:
- An archive per platform: Linux x86_64 and arm64, macOS universal, Windows x86_64 and, from 0.4.0, Windows arm64.
- Homebrew (macOS and Linux):
brew install hodeitek/hodeishield/hodeishield. Use the fully-qualified name: it adds the tap and trusts only that formula. - Scoop (Windows):
scoop bucket add hodeishield https://github.com/Hodeitek/scoop-hodeishieldand thenscoop install hodeishield. - Signed APT and DNF repositories at
packages.hodeishield.com(Debian, Ubuntu, Fedora, RHEL and compatible; x86_64 and arm64), from 0.6.0. See Install with APT or DNF. .deband.rpmpackages (Linux, x86_64 and arm64), from 0.3.0.- The Windows installer (
.msi). - A container image:
ghcr.io/hodeitek/hodeishield-cli. install.sh, signed, for Linux and macOS, from 0.3.0.
Install with APT or DNF¶
The packages.hodeishield.com repositories are signed, and your system's normal upgrades keep
the CLI current. Add the repository for your distribution (apt on Debian and Ubuntu, dnf on
Fedora, RHEL, Rocky Linux and AlmaLinux), then run sudo apt install hodeishield or
sudo dnf install hodeishield.
Before you trust the repository key, check its fingerprint. The exact commands, including the key download, the fingerprint check and the repository definition for each package manager, are in the CLI README; follow them as written instead of assembling your own. The fingerprint is published there only.
Authenticate¶
With a tenant API key (scripts, CI, servers)¶
Create a key in the app under Settings › Integrations and development › Integrations › API Key, with only the read scopes you need, and export it:
When HODEISHIELD_API_KEY is set it is used for every call, whatever else is configured.
Keep it in your CI's secret store; the CLI never prints it.
hodeishield whoami asks the API who the credential is and shows the tenant it reads (name
and id), its organisation and, for a key, its scopes; for a portfolio key, the MSSP and how many
client tenants it can select. With --json these are the tenant, organization, portfolio
and credential_scopes fields.
By signing in (people)¶
hodeishield login # opens the browser; the app redirects back to 127.0.0.1
hodeishield login --device # no browser here: approve a short code from another device
hodeishield whoami
hodeishield logout # revokes the token at the app and removes it from the keychain
You sign in to app.hodeishield.com as usual (2FA, passkey or
SSO), and on the consent screen you choose the one tenant the CLI may read. A sign-in
token never covers more than that tenant, and it only reads. To use an unrelated tenant, sign in
again with another profile (--profile). An MSSP does not need a profile per client: it uses a
portfolio key, see Several tenants (MSSP).
With --device, open the address the CLI prints on any device and type the code by
hand: the app does not accept a link with the code filled in, on purpose.
The token is kept in the system keychain (macOS Keychain, Windows Credential Manager, or the Secret Service — GNOME Keyring, KWallet — on Linux) and refreshed automatically, also when the app ends an access token early. Without a keychain, signing in is refused rather than falling back to a file: use an API key there, which is also the right choice for unattended automation.
On a server or container you control where you want to sign in as yourself, you can opt in to
a plain-text token file with HODEISHIELD_TOKEN_STORE=plaintext-file (or hodeishield config
set token_store plaintext-file). The default stays keychain. The tokens are then stored
unencrypted in a file only your user can read, so anyone who can read your files can use
them; it is an explicit choice, never a fallback, and it is not available on Windows yet.
To cut the CLI's access from elsewhere, revoke it in the app under Account → Application access.
Use¶
hodeishield vendors list --criticality critical
hodeishield vendors get 0b8f2a52-6a0e-4d5c-9d3e-1f2a3b4c5d6e
hodeishield alerts list --status open --since 2026-01-01T00:00:00Z
hodeishield risks list --min-inherent-score 15 --sort inherent_score
hodeishield compliance posture nis2
hodeishield compliance controls --framework nis2 --status failing
hodeishield evidence list --expiring-before 2026-12-31T00:00:00Z
hodeishield endpoints list --status active
Lists show one page (50 items by default); --page, --per-page (up to 200) and --all
walk the rest. Every list takes --sort and --order; --help on any command lists what
it accepts.
Reports¶
reports list and reports get show the reports generated for the tenant; reports download
saves a completed report's file. They need the reports:read scope.
hodeishield reports list --status completed
hodeishield reports get 7d3e1f2a-4b5c-4d6e-8f70-81a2b3c4d5e6 # includes the formats it can be downloaded in
hodeishield reports download 7d3e1f2a-4b5c-4d6e-8f70-81a2b3c4d5e6 --format xlsx --locale es
reports list filters by --type, --status and --since. --format is pdf (the default)
or xlsx; --locale is one of es, en (the default), de, fr, it and eu. The file is
saved in the current directory, or at --output <PATH>; an existing file is only replaced with
--force. A report that is still being generated, failed or has no file in that format is
refused with a message that says so.
JSON for scripts¶
--json prints the body the API returned, unchanged, including fields newer than your CLI.
With --all, it prints a single JSON array of every item:
CSV for spreadsheets¶
--csv prints the items of any list command (and of compliance controls) as CSV instead
of a table; it works with --all and not with --json:
Read requests are retried automatically (up to twice, with backoff) when the API answers 502, 503 or 504, or the connection fails.
Exit codes¶
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Error (invalid input, configuration, unexpected answer) |
| 2 | Invalid command line |
| 3 | Not authenticated: no credential (also when the system keychain cannot be reached in this session), or the API rejected it |
| 4 | The credential lacks the scope the command needs |
| 5 | Not found (or not in your organisation) |
| 6 | Rate limit exhausted (the CLI already retried short waits) |
| 7 | The API could not be reached or failed, or does not offer portfolio access yet |
| 8 | The tenant's license is not in force: a tenant administrator must renew or reactivate it |
Errors go to stderr with a hint and, when the API gave one, a request id: quote it when
you contact support. --verbose logs each request's method, URL, status and request id to
stderr, never a credential.
Several tenants (MSSP)¶
An MSSP reads all of its client tenants with one credential, a portfolio key, instead of one key or one profile per client.
How the key is scoped
- It is created in the app by an organisation administrator of an active MSSP organisation, in the MSSP area (API keys). Nobody else can create one: not a tenant administrator, and not a platform operator acting outside an MSSP organisation.
- It starts with
hsp_, reads only unless an organization administrator granted italerts:write(which allows acknowledging and resolving alerts through/v1, see Authentication; the CLI itself stays read-only), always expires (90 days by default, 365 at most) and works on the HodeiShield API only. - When it is created it can be limited to some of your clients and to source IP ranges. A request from another address is refused like an unknown key (exit code 3).
- Signing in with
hodeishield logindoes not cover a whole portfolio: use the key. - Rotate it before it expires: a new key and its predecessor both work for up to 7 days while the old one is in force. Revoke it in the same MSSP area; it stops working on its next request.
Use it like any other key
export HODEISHIELD_API_KEY=hsp_... # the portfolio key; keep it in your CI's secret store
hodeishield tenants list
$ hodeishield tenants list
SLUG NAME ORGANISATION TYPE STATUS LICENCE ID
acme Acme S.L. Acme Group client active in_force 11111111-1111-4111-8111-111111111111
beta Beta Corp Beta Group client active grace 22222222-2222-4222-8222-222222222222
tenants list shows the tenants the key may read: your own organisation's (TYPE own) and your
clients, including inactive ones or those without a licence in force, which STATUS and LICENCE
tell apart. It takes --json, --csv, --page and --all. The list is read from the API each
time, so a client added to or removed from your portfolio shows up on the next command.
Select the client
The selection goes with each command and is never remembered, so a later command cannot read another client by surprise.
hodeishield --tenant acme vendors list # one client, by slug or id
hodeishield --all-tenants alerts list --status open
hodeishield --all-tenants vendors list --criticality critical --csv > critical-vendors.csv
--tenant <slug|id>works on every read command (list,get,compliance posture). The CLI printsClient tenant: acme (<id>)on standard error, so a log shows which client was read.--all-tenantsworks onlistcommands and oncompliance controls. It reads every client one after the other (--per-pageapplies,--pagedoes not) and adds the tenant to each row: aTENANTcolumn in the table andtenant_id,tenant_slugandtenant_namein--jsonand--csv.--tenantand--all-tenantscannot be combined.
hodeishield --all-tenants alerts list --status open --json \
| jq -r '.[] | [.tenant_slug, .severity, .title] | @tsv'
If you call the API directly, the client is chosen with the X-HS-Tenant
header, which takes the tenant's id (a UUID), never a slug; see the
API reference.
What is refused
- Without
--tenantor--all-tenants, a portfolio key is refused by the API and the CLI tells you to choose. - A client that is not in your portfolio, or that you mistyped, fails with exit code 5 before anything is read. The two cases are one answer.
- A client you named that is deactivated, or whose licence is not in force, fails with exit code 8.
- A tenant API key or a sign-in asked for a client fails with exit code 4: it lacks the portfolio scope. Without those options they behave as before.
- With
--all-tenants, a client that cannot be read (inactive, licence not in force, not found, or a licence status this CLI version does not know) is named on standard error and skipped. The command prints the other clients and then exits non-zero, so a script never takes a partial result for a complete one: check the exit code and read standard error to see which clients were left out. - A slug that looks like another client's id is refused as ambiguous: use the id shown by
tenants list. - Rate limits apply per portfolio key (100 requests per minute) and to all the portfolio keys of
your organisation together (600); the API may change these numbers, and a client's own limits can
be lower. When one is exhausted the command stops with exit code 6 and says which limit it hit.
Use
--per-page 200and filters to need fewer requests. - Against an API that does not offer portfolio access yet, these options fail with exit code 7.
Configure¶
Settings come from, in order: flags, environment variables, the profile in the
configuration file, and the defaults (https://api.hodeishield.com,
https://app.hodeishield.com).
hodeishield config show # the settings in effect
hodeishield config path # where the file is
hodeishield --profile staging config set api_url https://api.example.test
hodeishield config use staging # make it the default profile
hodeishield --profile default vendors list # or pick one per command
| Variable | Purpose |
|---|---|
HODEISHIELD_API_KEY |
Tenant API key or MSSP portfolio key (hsp_...); takes precedence over a sign-in |
HODEISHIELD_PROFILE |
Profile to use |
HODEISHIELD_API_URL |
API base URL |
HODEISHIELD_APP_URL |
App base URL (sign-in) |
HODEISHIELD_CONFIG |
Path of the configuration file |
HODEISHIELD_TOKEN_STORE |
Where sign-in tokens are kept: keychain (the default) or plaintext-file, an explicit opt-in; takes precedence over token_store in the configuration file |
HODEISHIELD_NO_UPDATE_CHECK |
Any non-empty value turns off the one-line new-version notice (also hodeishield config set update_check false) |
The configuration file holds URLs and sign-in settings only, never a credential (the opt-in
token file is a separate file). URLs must
use HTTPS; plain HTTP is accepted only for localhost.
Shell completions: hodeishield completions bash|zsh|fish|powershell|elvish.
Next step¶
- MCP server — the same API, hosted, nothing to install
- API overview
- Repository on GitHub