Skip to content

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 GET against /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. --json prints the API's own JSON, exit codes say what went wrong, and HODEISHIELD_API_KEY works 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-hodeishield and then scoop 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.
  • .deb and .rpm packages (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:

export HODEISHIELD_API_KEY=hsk_...
hodeishield whoami

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:

hodeishield alerts list --status open --all --json | jq -r '.[] | [.severity, .title] | @tsv'

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:

hodeishield vendors list --all --csv > vendors.csv

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 it alerts: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 login does 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 prints Client tenant: acme (<id>) on standard error, so a log shows which client was read.
  • --all-tenants works on list commands and on compliance controls. It reads every client one after the other (--per-page applies, --page does not) and adds the tenant to each row: a TENANT column in the table and tenant_id, tenant_slug and tenant_name in --json and --csv.
  • --tenant and --all-tenants cannot 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 --tenant or --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 200 and 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