All Commands

npx asen init

Initializes Agentinel in your project. Auto-detects installed AI agents and writes the appropriate hook configurations. Also installs a Git pre-commit hook that scans your staged lockfile on every commit.

Flags

Example output

  agentinel v1.0.0 initialized

  Hooks wired:
    Claude Code   hooks.json        OK
    Codex CLI     .codex/config     OK
    Copilot CLI   .copilot/config   OK
    Gemini CLI    .gemini/config    OK

  Git pre-commit hook installed.
  Config written to .agentinel.json

  Run `npx asen check` to scan your current lockfile.

Exit codes

Notes

• Running asen init multiple times is safe. It will merge hook config rather than overwrite it.
• The Git pre-commit hook calls npx asen check on every commit. This adds ~100ms to commit time.
• asen init respects the .agentinel.json mode setting when writing the hook runner command.

npx asen init --shim

Runs the standard init flow and additionally installs a global PATH shim that wraps the npm binary. Any npm install command from any source (not just AI agents) will be intercepted by Agentinel.

Example output

  agentinel v1.0.0 initialized

  PATH shim installed:
    Shell profile:  ~/.zshrc
    Shim binary:    ~/.agentinel/bin/npm
    Real npm at:    /usr/local/bin/npm

  All npm install calls will now be intercepted.
  To remove the shim, run `npx asen unshim`.

Exit codes

Notes

• The shim modifies your shell profile (~/.zshrc, ~/.bashrc, etc.) to prepend ~/.agentinel/bin to your PATH.
• To remove the shim cleanly without leaving dangling PATH entries, always use npx asen unshim rather than deleting files manually.
• The shim only intercepts npm install and npm i. Other npm commands (npm run, npm test, etc.) are passed through immediately.

npx asen check

Scans your staged lockfile dependencies against the OSV database and heuristics. Designed for use in CI/CD pipelines and Git pre-commit hooks. Exits with code 1 if any flagged packages are found.

Flags

Example output

  Scanning 127 staged lockfile dependencies...

  WARN  some-new-package@1.0.0
        Reason: Low download count (892). Age: 3 days.

  BLOCK lodash-utils-extended@2.1.0
        Reason: OSV match MAL-2026-1142

  Scan complete: 1 blocked, 1 warning, 125 clean.
  Exit code: 1

Exit codes

Notes

• When run in a CI environment (CI=true), output is automatically formatted for log readability.
• The pre-commit hook installed by asen init runs this command automatically on every git commit.
• Packages in your allowlist are skipped and counted as clean.

npx asen check <package-name>

Instantly scans a single named package against the OSV database and heuristics. Useful for quickly checking a package before manually installing it, or for scripting package validation.

Flags

Example output

  npx asen check lodash

  Scanning lodash@latest...

  CLEAN lodash@4.17.21
        No OSV records. Heuristics: pass.
        Downloads: 82,400,000/week. Age: 3,841 days.

  Exit code: 0

Exit codes

Notes

• This command makes one npm registry call to resolve the latest version number if --version is not specified.
• All other data (OSV lookup, heuristics) is resolved locally from the bundled DB.
• For unknown packages (ghost packages), the check exits immediately with a BLOCK signal.

npx asen allow <package-name> --reason <reason>

Adds a package to the allowlist in .agentinel.json with a required reason string. The entry includes an audit trail (who added it and when) and is committed to version control so the team has visibility.

Flags

Example output

  npx asen allow my-internal-pkg --reason "Internal monorepo package"

  Added to allowlist:
    Package:  my-internal-pkg
    Reason:   Internal monorepo package
    Added by: aman@company.com
    Added at: 2026-07-14T09:32:11.000Z

  .agentinel.json updated.

Exit codes

Notes

• The --reason flag is required. Running asen allow without it will print an error and exit with code 1.
• The addedBy field is populated from git config user.email. If git is not configured, it falls back to the system username.
• Allowlisted packages bypass both OSV matching and heuristic checks, except for npm takedown markers, which always block regardless of the allowlist.

npx asen unshim

Removes the global PATH shim installed by asen init --shim. Cleans up the shim binary and removes the PATH entry from your shell profile. The real npm binary is restored to its original position.

Flags

Example output

  npx asen unshim

  Removing PATH shim...
    Removed: ~/.agentinel/bin/npm
    Updated: ~/.zshrc (removed PATH prepend)

  The real npm at /usr/local/bin/npm is active again.
  Restart your shell or run `source ~/.zshrc` to apply.

Exit codes

Notes

• Always use asen unshim rather than manually deleting the shim binary. Manual deletion leaves a dangling PATH entry in your shell profile.
• After running unshim, restart your shell session or source your shell profile for the change to take effect.
• asen unshim has no effect if the shim was never installed.