README
¶
cli-guard
cli-guard is a security-boundary framework for urfave/cli v3 applications, designed to sit between AI agents (or any semi-trusted automation) and the host system, featuring:
- argv validation rejecting shell metacharacters before they reach
execve - append-only JSONL audit log with lumberjack rotation
- read / write / delete scope tokens, validated per verb
--commit-scoperesolution binding every audit row to a git toplevel- clean+synced gate refusing repo-shaped verbs on a dirty tree
- per-repo command allowlist loaded from per-repo YAML config files (e.g.
.agent-guard/agent-guard.yaml,.coily/coily.yaml) - thin pass-through wrapper for embedding existing CLIs as audited subcommands
- per-invocation CONNECT proxy with consumer-supplied egress allowlist
- public exit-code taxonomy for orchestrators
Documentation
See docs/FEATURES.md for a feature inventory, examples/ for runnable demos one per primitive, and the CLI reference for the rendered command tree of every example. Local dev verbs live in .agent-guard/agent-guard.yaml; agent-guard lint validates that against the Makefile.
Support
If you found a bug or have a feature request, create a new issue. Participation in this community is governed by the Code of Conduct. Security disclosures go through SECURITY.md.
Sibling repos in the cli-* family: cli-mcp, cli-web-docs, cli-web-ops.
License
See LICENSE.
See also
- AGENTS.md - agent-facing operating rules.
- docs/FEATURES.md - inventory of what ships today.
- .agent-guard/agent-guard.yaml - allowlisted commands.
Cross-reference convention from coilysiren/agentic-os#59.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package audit writes one JSONL record per CLI invocation to an append-only log outside the working tree.
|
Package audit writes one JSONL record per CLI invocation to an append-only log outside the working tree. |
|
Package config carries the layered-config primitives shared across cli-guard consumers: path helpers, repo-slug derivation, the Audit rotation knobs, ExpandHome, and a generic OverlayFile helper.
|
Package config carries the layered-config primitives shared across cli-guard consumers: path helpers, repo-slug derivation, the Audit rotation knobs, ExpandHome, and a generic OverlayFile helper. |
|
Package decision is the per-call profile-aware evaluator: takes a session profile name, resolves it through the profiles registry, and returns an audit.ProfileDecision suitable for attaching to an audit row.
|
Package decision is the per-call profile-aware evaluator: takes a session profile name, resolves it through the profiles registry, and returns an audit.ProfileDecision suitable for attaching to an audit row. |
|
Package egress is the per-invocation HTTP CONNECT proxy that coily starts for the duration of a wrapped subprocess.
|
Package egress is the per-invocation HTTP CONNECT proxy that coily starts for the duration of a wrapped subprocess. |
|
examples
|
|
|
audit
command
Command demo is a tiny urfave/cli v3 application that exercises the cli-guard framework primitives.
|
Command demo is a tiny urfave/cli v3 application that exercises the cli-guard framework primitives. |
|
egress
command
Command egress demonstrates the per-invocation CONNECT proxy with a pinned allowlist.
|
Command egress demonstrates the per-invocation CONNECT proxy with a pinned allowlist. |
|
exitcode
command
Command exitcode demonstrates the public exit-code taxonomy.
|
Command exitcode demonstrates the public exit-code taxonomy. |
|
gittree
command
Command gittree demonstrates the clean+synced gate.
|
Command gittree demonstrates the clean+synced gate. |
|
passthrough
command
Command passthrough demonstrates wrapping an existing binary as an audited urfave/cli subcommand.
|
Command passthrough demonstrates wrapping an existing binary as an audited urfave/cli subcommand. |
|
policy
command
Command policy demonstrates argv-validation rejection.
|
Command policy demonstrates argv-validation rejection. |
|
repocfg
command
Command repocfg demonstrates loading a per-repo command allowlist.
|
Command repocfg demonstrates loading a per-repo command allowlist. |
|
scope
command
Command scope demonstrates --commit-scope resolution.
|
Command scope demonstrates --commit-scope resolution. |
|
treebuilders
Package treebuilders exports each examples/<name>/main.go's *cli.Command tree so scripts/gen-webdocs can render it, and so each example main stays a thin shim that drives the tree.
|
Package treebuilders exports each examples/<name>/main.go's *cli.Command tree so scripts/gen-webdocs can render it, and so each example main stays a thin shim that drives the tree. |
|
Package exitcode is the public contract for what the process exit code means.
|
Package exitcode is the public contract for what the process exit code means. |
|
Package ghcache caches GitHub REST `GET` responses keyed by method, path, body, and token fingerprint, with method-aware write-through invalidation.
|
Package ghcache caches GitHub REST `GET` responses keyed by method, path, body, and token fingerprint, with method-aware write-through invalidation. |
|
Package ghidcache caches GitHub identity reads - `gh auth status` and `gh api user` - that re-resolve on every coily invocation but are stable for hours.
|
Package ghidcache caches GitHub identity reads - `gh auth status` and `gh api user` - that re-resolve on every coily invocation but are stable for hours. |
|
Package ghratelimit retries gh-CLI calls that fail with a GitHub rate-limit error.
|
Package ghratelimit retries gh-CLI calls that fail with a GitHub rate-limit error. |
|
Package gittree inspects a repo's working tree for the clean+synced state that gates `.coily/coily.yaml` repo verbs.
|
Package gittree inspects a repo's working tree for the clean+synced state that gates `.coily/coily.yaml` repo verbs. |
|
Package hook implements the Claude Code PreToolUse hook engine in the shared substrate.
|
Package hook implements the Claude Code PreToolUse hook engine in the shared substrate. |
|
Package lockdown writes a per-repo Claude Code settings file that enforces an allowlist-inversion for the wrapper binary supplied by a Driver.
|
Package lockdown writes a per-repo Claude Code settings file that enforces an allowlist-inversion for the wrapper binary supplied by a Driver. |
|
Package passthrough is the thin pass-through used to wrap any sub-CLI (aws, gh, kubectl, docker, tailscale, plus every package manager) as a single `coily <bin> ...` verb.
|
Package passthrough is the thin pass-through used to wrap any sub-CLI (aws, gh, kubectl, docker, tailscale, plus every package manager) as a single `coily <bin> ...` verb. |
|
Package policy validates that verb arguments do not contain shell metacharacters.
|
Package policy validates that verb arguments do not contain shell metacharacters. |
|
Package profile declares the categorical operating-model axes that cli-guard exposes for consumers (today: coily) to build per-session profiles on top of.
|
Package profile declares the categorical operating-model axes that cli-guard exposes for consumers (today: coily) to build per-session profiles on top of. |
|
Package profiles loads the per-host lockdown profile registry from ~/.coily/coily.yaml and resolves named profiles to cli-guard/profile Coordinates.
|
Package profiles loads the per-host lockdown profile registry from ~/.coily/coily.yaml and resolves named profiles to cli-guard/profile Coordinates. |
|
Package repocfg loads a per-repo command allowlist from a coily.yaml file discovered by walking up from the current working directory.
|
Package repocfg loads a per-repo command allowlist from a coily.yaml file discovered by walking up from the current working directory. |
|
Package respfmt renders a JSON response body through an optional JMESPath projection and one of five output formats: yaml (default), json, text, table, yaml-stream.
|
Package respfmt renders a JSON response body through an optional JMESPath projection and one of five output formats: yaml (default), json, text, table, yaml-stream. |
|
Package scope resolves the --commit-scope flag value into the absolute repo path that an audit record should be bound to.
|
Package scope resolves the --commit-scope flag value into the absolute repo path that an audit record should be bound to. |
|
Package shell is the argv-only exec wrapper.
|
Package shell is the argv-only exec wrapper. |
|
Package skillgen renders an urfave/cli v3 command tree into either a flat markdown lookup table or a structured yaml document.
|
Package skillgen renders an urfave/cli v3 command tree into either a flat markdown lookup table or a structured yaml document. |
|
Package ssh is the Go-SDK boundary for ssh and scp.
|
Package ssh is the Go-SDK boundary for ssh and scp. |
|
Package stscache caches `aws sts get-caller-identity` JSON for callers that re-resolve the active AWS identity on every coily invocation.
|
Package stscache caches `aws sts get-caller-identity` JSON for callers that re-resolve the active AWS identity on every coily invocation. |
|
Package sudo is policy-free plumbing for driving an interactive sudo over an ssh transport without either (a) carrying a password at rest or (b) leaking it through argv or the audit log.
|
Package sudo is policy-free plumbing for driving an interactive sudo over an ssh transport without either (a) carrying a password at rest or (b) leaking it through argv or the audit log. |
|
Package ttlcache is a small on-disk key/value cache with per-entry TTLs.
|
Package ttlcache is a small on-disk key/value cache with per-entry TTLs. |
|
Package verb is the middleware that wraps every coily command action in the standard pipeline of:
|
Package verb is the middleware that wraps every coily command action in the standard pipeline of: |
|
Package workdir does best-effort detection of the "primary working directory" that a coily invocation is operating against.
|
Package workdir does best-effort detection of the "primary working directory" that a coily invocation is operating against. |
Click to show internal directories.
Click to hide internal directories.