Skip to main content

CLI: Command-Line Interface

Overview​

The Packmind CLI provides two main commands:

  • pull - Download packages locally
  • lint - Run detection programs (Enterprise only)

Installation​

Option 1: npm Package​

Global Installation:

npm install -g @packmind/cli

After installation, the packmind-cli command will be available globally.

npx (no installation required):

npx @packmind/cli pull --list

This runs the CLI directly without installing it, always using the latest version.

Option 2: Standalone Executables​

Download the appropriate pre-built executable for your platform from the GitHub Releases page.

Available platforms:

  • Linux x64: packmind-cli-linux-x64-{version}
  • Linux arm64: packmind-cli-linux-arm64-{version}
  • macOS arm64: packmind-cli-macos-arm64-{version} (signed and notarized)
  • Windows x64: packmind-cli-windows-x64-{version}.exe

For Linux/macOS, make the executable runnable:

chmod +x packmind-cli-*-{version}

Optional: Move to a directory in your PATH for easy access:

# Linux/macOS
sudo mv packmind-cli-*-{version} /usr/local/bin/packmind-cli

# Windows: Move to a directory in your PATH or run directly
Choosing an Installation Method
  • Use npm global if you want packmind-cli always available system-wide
  • Use npx for project-specific usage or testing without installation
  • Use standalone executables if you don't have Node.js installed or need a specific binary for your environment

Authentication​

The CLI requires an API key to authenticate with your Packmind instance.

Getting Your API Key​

  1. Log in to your Packmind instance (Cloud or self-hosted)
  2. Navigate to Settings (click your profile icon in the top right)
  3. Scroll to the API Key section
  4. Click Generate New Key to create an API key (valid for 90 days)
  5. Copy the generated key

Setting the API Key​

Set the API key as an environment variable:

export PACKMIND_API_KEY_V3="your-api-key-here"

To make this permanent, add it to your shell configuration file (~/.bashrc, ~/.zshrc, etc.):

echo 'export PACKMIND_API_KEY_V3="your-api-key-here"' >> ~/.zshrc
source ~/.zshrc

Pull Command​

Download recipes and standards from packages to your local machine.

List Available Packages​

packmind-cli pull --list

View Package Details​

packmind-cli pull --show <package-slug>

Pull Packages​

packmind-cli pull <package-slug> [additional-package-slugs...]

Example:

packmind-cli pull backend frontend

This downloads all recipes and standards from the specified packages and creates the appropriate files for your AI coding assistant.

AI Agent Rendering

The files created by the pull command depend on which AI agents are enabled in your organization settings. The CLI respects your organization's configured agents and creates instruction files accordingly (e.g., AGENTS.md, .cursor/rules/, .github/copilot-instructions.md).

The .packmind/ directory is always created regardless of your configuration.

To configure which agents are enabled, see Manage AI Agent Rendering.

Lint Command​

Enterprise Feature

The lint command is only available in the Enterprise edition.

Run detection programs against your codebase from the command line. This is useful for testing draft detection programs, verifying active programs, and integrating linting into your development workflow or CI/CD pipelines.

How Lint Works​

The CLI supports two linting modes:

Local Mode (recommended):

When you have packmind.json files in your project, the CLI uses them to determine which standards to check against. The CLI automatically searches for all packmind.json files in your project tree:

  • Ancestor configs: Searches parent directories up to the Git repository root
  • Descendant configs: Searches subdirectories from your current location

All standards from packages defined in these packmind.json files are included in the analysis scope. This allows different parts of your codebase to have different standards while inheriting common standards from parent directories.

To set up local linting, install packages using the install command. See Distribute Standards and Recipes for details.

Deployment Mode:

If no packmind.json files are found, the CLI falls back to using standards that have been deployed to your Git repository through the web interface. See Deployment to learn about this approach.

Priority

When both local packmind.json files and deployments exist, the local configuration takes priority.

Basic Usage​

packmind-cli lint .

This command:

  • Searches for packmind.json files in your project tree
  • Loads detection programs from the standards defined in your packages
  • Scans all files in the current directory (excluding node_modules, dist, and other common build folders)
  • Runs all active detection programs
  • Reports any violations found

Specify a Path​

Lint a specific directory or file:

packmind-cli lint src/
packmind-cli lint /path/to/your/project

Limiting Scope with --diff​

When working on large codebases, you can focus the lint check on only the files or lines you've modified using the --diff option.

Git Repository Required

The --diff option requires your project to be in a Git repository.

Check modified lines only:

packmind-cli lint . --diff=lines

This analyzes only the specific lines you've changed, making it ideal for pre-commit hooks or reviewing your work before pushing.

Check modified files only:

packmind-cli lint . --diff=files

This analyzes all content in files you've modified, useful when you want full context but don't want to scan the entire codebase.

Example workflow:

# Make some changes to your code
git add .

# Check only what you changed
packmind-cli lint . --diff=lines

# If clean, commit
git commit -m "Your changes"

Output Formats​

Choose between human-readable and IDE-friendly output:

packmind-cli lint . --logger=ide

Human-readable format (default) shows:

  • File paths with violations
  • Line and character positions
  • Rule identifiers
  • Summary of total violations found

IDE format provides structured output that can be parsed by editors and CI/CD tools.