Commands - HiddenLayer Docs

The following are details and examples for the Agent Harness Security CLI commands.

General Scheme

hl <command> [<subcommand>] [flags ...]

Tree

hl
├── help
├── status
├── version
├── config
│   ├── get
│   ├── set --global
│   └── unset --global
├── discover
│   └── <TBD>
└── runtime
    ├── auth
    ├── setup   [harness]
    ├── unsetup [harness]
    └── agent   --harness --hook

Informational Commands

Help

Description

Displays usage text.

Input Flags

None

Exit Codes

0 - Always

Example

$ hl help

This is the HiddenLayer On-Device Binary.

USAGE
  hl <command> [<subcommand>] [flags ...]

INFORMATIONAL COMMANDS
  help:         This usage text
  status:       Show status of config and auth
  version:      Show version information

FUNCTIONAL COMMANDS
  discover:     Discover locally-installed MCP and skills
  runtime:      Manage agent hooks and evaluate provider interactions

LEARN MORE
  Read the manual at https://hiddenlayer.ai/foo/bar

Status

Description

Shows configured values for:
- Client ID: *** if populated, <empty> if empty.
- Client secret: *** if populated, <empty> if empty.
- Project ID
- Requester ID
- HiddenLayer Platform URL

Input Flags

--verbose: Add additional details around how we resolve multiple configuration sources into final values.

Exit Codes

0 - Always

Examples Default Behavior

$ hl status
client_id:       ***
client_secret:   ***
project_id:      1a2b34c5-d67e-8f90-1234-g56789hij012
requester_id:    user@acme.com
HL Platform URL: https://api.hiddenlayer.ai

Verbose

$ hl status --verbose
client_id:       z99y8x77-w654-32v1-ut09-8sr76543q2p1
  · env                  HIDDENLAYER_CLIENT_ID (not set)
  ✓ config-file          "z99y8x77-w654-32v1-ut09-8sr76543q2p1"
  · global-config-file   (not set)

client_secret:   ***
  · env                  HIDDENLAYER_CLIENT_SECRET (not set)
  ✓ secrets              ***

project_id:      <empty>
  · env                  HIDDENLAYER_PROJECT_ID (not set)
  · config-file          (not set)
  · global-config-file   (not set)

requester_id:    <empty>
  · env                  HIDDENLAYER_REQUESTER_ID (not set)
  · config-file          (not set)
  · global-config-file   (not set)

platform_url:    https://api.hiddenlayer.ai
  · env                  HIDDENLAYER_PLATFORM_URL (not set)
  ✓ config-file          "https://api.hiddenlayer.ai"
  · global-config-file   (not set)

Sources:
  env                  Environment variables
  config-file          /Users/name/Library/Application Support/HiddenLayer/config.toml
  global-config-file   /Library/Application Support/HiddenLayer/config.toml
  secrets              macOS Keychain: com.hiddenlayer.odb

Version

Description

Display the plug-in version.

Input Flags

None

Exit Codes

0 - Always

Example

$ hl version
hl version <commit> <date>

Functional Commands

Config

Description

Displays usage text for the config command and groups its subcommands.
Run hl config with no subcommand to print help.

Input Flags

None

Exit Codes

0 - Always (prints usage)

Example

$ hl config
Get, set, and unset configuration values

Usage:
  hl config [command]

Available Commands:
  get         Print a configuration value (secrets are masked)
  set         Set a configuration value (secrets go to the OS secret store)
  unset       Remove a configuration value

Flags:
  -h, --help   help for config

Config Get

Description

Prints the effective value of a configuration field.

Input Flags

None

Exit Codes

0 - The field has a value (printed to stdout; secrets shown as ***).
1 - Any other error (e.g. an unknown field name — reported on stderr).
2 - The field is unset (nothing printed).

Example

$ hl config get client_id
 my-client-id
$ echo $?
 0

Secret (masked):
$ hl config get client_secret
  ***
$ echo $?
 0

Unset field — exit 2, no output:
$ hl config get project_id
$ echo $?
  2

Unknown field — exit 1, error on stderr:
$ hl config get not-a-field
  Error: unknown config field "not-a-field"; valid fields: client_id, client_secret, project_id, requester_id, platform_url
$ echo $?
  1

Config Set

Description

Writes a value for the configuration field.

Input Flags

--global: Write to the machine-scoped global config file instead of the per-user file. Ignored by the secret fields.

Exit Codes

0 - Value stored.
1 - Failure: unknown field; a secret field on a platform with no secret store; config-file path unresolvable; or a write/permission error.

Example

Replace my-client-id with the API key.
Replace my-client-secret with the API secret.
For platform_url, use https://api.eu.hiddenlayer.ai for the EU region.

Plain field (user config file):
$ hl config set client_id my-client-id
Set client_id.

Secret (routed to the OS secret store, value not echoed):
$ hl config set client_secret my-client-secret
Set client_secret.

Global scope (machine-wide; typically needs admin/root):
$ hl config set --global platform_url https://api.hiddenlayer.ai
Set platform_url.

Config Unset

Description

Removes a configuration field value.

Input Flags

--global: Remove from the machine-scoped global config file instead of the per-user file. Ignored for secret fields.

Exit Codes

0 - Value removed (or already absent).
1 - Failure (same modes as set).

Example

$ hl config unset project_id
Unset project_id.

Runtime

Description

Displays usage text for the runtime command.

Input Flags

None

Exit Codes

0 - Always

Example

$ hl runtime
Evaluate a provider interaction

Usage:
  hl runtime [command]

Available Commands:
  agent       Evaluate an interaction for an agent hook
  auth        Check authentication status
  setup       Install HiddenLayer agent hooks into supported harnesses
  unsetup     Remove HiddenLayer agent hooks from supported harnesses

Flags:
  -h, --help   help for runtime

Runtime Auth

Description

Connectivity check.

Input Flags

None

Exit Codes

0 - If JWT retrieval was successful.
1 - Otherwise.

Examples Success

$ hl runtime auth
✓ Read configuration from /home/johndoe/.hiddenlayer/config
✓ Connected to the HL platform
✓ Retrieved a JWT
✓ Examines JWT for inference:write scope
✓ Succeeded

Failure

$ hl runtime auth
✓ Read configuration from /home/johndoe/.hiddenlayer/config
✓ Connected to the HL platform
✗ Invalid credentials
✗ Failed

Runtime Setup

Description

Installs or repairs the HiddenLayer agent hooks for supported harnesses.
Accepts an optional positional [harness] argument, naming a single harness to target (like claude-code). When omitted, all registered harnesses are targeted.
Absent harnesses are detected automatically and skipped, so they will not cause a failure.
Safe to run at any time. If the hook already current, reports back already up to date. If the hook has drifted from the expected configuration, the hook is repaired and repaired hooks (config has drifted) message displays.

Input Flags

[harness]: Optional positional argument; one of the registered harness names (like claude-code). When omitted, all registered harnesses are evaluated.

Exit Codes

0 - All targeted harnesses were processed successfully (outcome may be: installed, repaired, already up to date, or not installed and skipped).
1 - Any harness failed during setup, or an unknown harness name was provided as the positional argument.

Examples Fresh install (harness present on device, hooks not yet configured)

$ hl runtime setup
✓ claude-code: installed hooks
✓ Succeeded

Repair (hooks exist, but config has drifted)

$ hl runtime setup
✓ claude-code: repaired hooks (config had drifted)
✓ Succeeded

Already up to date

$ hl runtime setup
✓ claude-code: already up to date
✓ Succeeded

Harness not installed on device (skipped, not an error)

$ hl runtime setup
✓ claude-code: not installed, skipped
✓ Succeeded

Target a specific harness by name

$ hl runtime setup claude-code
✓ claude-code: installed hooks
✓ Succeeded

Unknown harness name

$ hl runtime setup not-a-harness
Error: unknown harness "not-a-harness"
$ echo $?
1

Runtime Unsetup

Description

Removes HiddenLayer agent hooks from supported harnesses.
Accepts an optional positional [harness] argument; behaviour is identical to runtime setup — omit to target all registered harnesses, or name one specifically.
Absence of hooks is treated as success; safe to re-run.

Input Flags

[harness]: Optional positional argument; one of the registered harness names (like claude-code). When omitted, all registered harnesses are evaluated.

Exit Codes

0 - Hooks removed (or already absent) for all targeted harnesses.
1 - Failure to remove hooks, or unknown harness name provided.

Examples Successful removal

$ hl runtime unsetup
✓ claude-code: removed hooks
✓ Succeeded

Harness not installed on device (skipped, not an error)

$ hl runtime unsetup
✓ claude-code: not installed, skipped
✓ Succeeded

Target a specific harness by name

$ hl runtime unsetup claude-code
✓ claude-code: removed hooks
✓ Succeeded

Runtime Agent

Description

Takes a hook payload from stdin.
Sends the payload to the HL Platform.
Returns the response to the host on stdout.

Input Flags

--harness: Exactly one of claude-code, cursor, codex, or github-copilot.
--hook: The name of the hook.

Exit Codes

0 - On successful hook execution that results in a non-BLOCK outcome.
1 - On failure to execute the hook.
2 - On successful hook execution that results in a BLOCK outcome.

Examples Benign

$ hl runtime agent --harness cursor --hook beforeSubmitPrompt -
// stdin - comes from cursor

// stdout - returned from hl
{
  "continue": true
}

Block

$ hl runtime agent --harness cursor --hook beforeSubmitPrompt -
// stdin - comes from cursor

// stdout - returned from hl
{
  "continue": false,
  "user_message": "this message has been blocked"
}

​General Scheme

​Tree

​Informational Commands

​Help

​Status

​Version

​Functional Commands

​Config

​Config Get

​Config Set

​Config Unset

​Runtime

​Runtime Auth

​Runtime Setup

​Runtime Unsetup

​Runtime Agent

General Scheme

Tree

Informational Commands

Help

Status

Version

Functional Commands

Config

Config Get

Config Set

Config Unset

Runtime

Runtime Auth

Runtime Setup

Runtime Unsetup

Runtime Agent