> ## Documentation Index
> Fetch the complete documentation index at: https://packmind-feat-rename-cli-packmind.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI: Command-Line Interface

## Overview

The Packmind CLI provides the following commands:

* **`init`** - Initialize Packmind in your project (configure agents + install skills)
* **`config agents`** - Configure which AI coding agents to generate artifacts for
* **`login`** - Authenticate with your Packmind instance
* **`logout`** - Clear stored credentials
* **`whoami`** - Show current authentication status
* **`setup-mcp`** - Configure MCP for AI coding agents
* **`install`** - Download packages locally
* **`uninstall`** - Remove packages from your project
* **`lint`** - Run detection programs (Enterprise only)
* **`skills add`** - Import skills into Packmind
* **`skills init`** - Install default Packmind skills locally
* **`skills list`** - List all skills in your organization
* **`standards create`** - Create a coding standard from a playbook file or stdin
* **`standards list`** - List all standards in your organization
* **`commands create`** - Create a reusable command from a playbook file or stdin
* **`commands list`** - List all commands in your organization
* **`packages create`** - Create a new package
* **`packages add`** - Add standards, commands, or skills to a package
* **`packages list`** - List all packages in your organization
* **`update`** - Update the CLI to the latest version

## Installation

### One-click install (Recommended)

The easiest way to install and configure the Packmind CLI is using the one-click install available in the Packmind web interface.

**Where to find it:**

* During your first onboarding after creating an account
* Anytime in your **Account Settings** page

**What it does:**

1. Downloads and installs the Packmind CLI binary for your platform
2. Authenticates you automatically with your Packmind account
3. Configures the Packmind MCP servers for AI coding agents detected on your machine (Claude Code, Cursor, VS Code/GitHub Copilot)
4. Sets up your PATH environment variable

Simply copy the provided command and paste it into your terminal. The script handles everything automatically.

<Tip>
  **Why this is recommended** — The one-click install eliminates manual steps by
  combining installation, authentication, and MCP configuration in a single
  command. It also detects which AI coding agents you have installed and
  configures them automatically.
</Tip>

### Alternative: npm Package

<Note>**Node.js 22 or higher required**.</Note>

**Global Installation**:

```bash theme={null}
npm install -g @packmind/cli
```

After installation, the `packmind` command will be available globally.

**npx** (no installation required):

```bash theme={null}
npx @packmind/cli install --list
```

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

### Alternative: Homebrew

Available on macOS and Linux.

```bash theme={null}
brew tap PackmindHub/cli
brew install packmind
```

After installation, the `packmind` command will be available globally.

### Alternative: Standalone Executables

Download the appropriate pre-built executable for your platform from the [GitHub Releases page](https://github.com/PackmindHub/packmind/releases?q=CLI\&expanded=true).

**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:

```bash theme={null}
chmod +x packmind-cli-*-{version}
```

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

```bash theme={null}
# Linux/macOS
sudo mv packmind-cli-*-{version} /usr/local/bin/packmind

# Windows: Move to a directory in your PATH or run directly
```

<Tip>
  **Choosing an Installation Method** — Use **one-click install** for the
  simplest experience with automatic authentication and MCP setup. Use **npm
  global** if you want `packmind` always available system-wide. Use **npx** for
  project-specific usage or testing without installation. Use **Homebrew** if
  you prefer managing packages through your system package manager
  (macOS/Linux). Use **standalone executables** if you don't have Node.js
  installed or need a specific binary for your environment.
</Tip>

## Authentication

The CLI requires authentication to communicate with your Packmind instance.

### Login Command (Recommended)

The easiest way to authenticate is using the `login` command:

```bash theme={null}
packmind login
```

This will:

1. Open your browser to the Packmind login page
2. After you authenticate, automatically receive credentials
3. Store credentials securely in `~/.packmind/credentials.json`

**For self-hosted instances**, specify your host:

```bash theme={null}
packmind login --host https://your-packmind-instance.com
```

**Manual code entry** (if browser flow doesn't work):

You can also enter a login code manually from the web interface:

```bash theme={null}
packmind login --code YOUR_CODE_HERE
```

### Logout Command

To clear stored credentials:

```bash theme={null}
packmind logout
```

This removes the credentials file. If you also have `PACKMIND_API_KEY_V3` set as an environment variable, you'll need to unset it separately:

```bash theme={null}
unset PACKMIND_API_KEY_V3
```

### Whoami Command

Check your current authentication status:

```bash theme={null}
packmind whoami
```

This displays:

* Your API key (masked)
* Connected host
* Organization name
* User name
* Credential expiration status

### API Key Authentication (PACKMIND\_API\_KEY\_V3)

You can authenticate using the `PACKMIND_API_KEY_V3` environment variable instead of the interactive login flow. This is the recommended approach for:

* **CI/CD pipelines** — Automated environments where interactive login isn't possible
* **Docker containers** — Pass the API key as an environment variable
* **Scripted workflows** — When you need non-interactive authentication

#### 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 **CLI Authentication** section
4. Go to the **Environment Variable** tab
5. Click **Generate New Key** to create an API key (valid for 90 days)
6. Copy the generated key

#### Setting the Environment Variable

Set the `PACKMIND_API_KEY_V3` environment variable with your API key:

```bash theme={null}
export PACKMIND_API_KEY_V3="your-api-key-here"
```

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

```bash theme={null}
echo 'export PACKMIND_API_KEY_V3="your-api-key-here"' >> ~/.zshrc
source ~/.zshrc
```

#### CI/CD Example (GitHub Actions)

```yaml theme={null}
- name: Install Packmind packages
  env:
    PACKMIND_API_KEY_V3: ${{ secrets.PACKMIND_API_KEY_V3 }}
  run: packmind install -r
```

<Tip>
  **Credential Priority** — When both a credentials file and the
  `PACKMIND_API_KEY_V3` environment variable exist, the environment variable
  takes precedence.
</Tip>

## Init Command

Initialize Packmind in your project. This is the recommended first command to run when setting up Packmind in a new project.

### What Init Does

The init command performs two main actions:

1. **Configures AI agents** - Interactively select which AI coding agents to generate artifacts for
2. **Installs default skills** - Including skill creator, standard creator, and onboarding skills

### Basic Usage

```bash theme={null}
packmind init
```

This will:

1. Present an interactive prompt to select which AI agents you use (Claude Code, Cursor, GitHub Copilot, etc.)
2. Save your agent configuration to `packmind.json`
3. Install Packmind's default skills to the appropriate locations for your selected agents
4. Display a success message with next steps

**Example output:**

```
Select coding agents to generate artifacts for:

  1. [*] Claude Code
  2. [ ] Cursor
  3. [ ] GitHub Copilot
  ...

Enter numbers separated by commas (default: 1,2,3): 1,2

Configuration saved. Artifacts will be generated for: Claude Code, Cursor

Installing default skills...
Default skills installed successfully!
  Files created: 5

Packmind initialized successfully!
Next step: Run /packmind-onboard in your AI agent to onboard the project
```

<Tip>
  **First-time setup** — Run `packmind init` after installing the CLI and
  logging in. It's the quickest way to get Packmind configured for your project.
  After initialization, use the `/packmind-onboard` skill in your AI agent to
  scan your project and generate project-specific standards and commands.
</Tip>

## Config Command

Configure Packmind settings.

### Config Agents

Configure which AI coding agents to generate artifacts for:

```bash theme={null}
packmind config agents
```

This presents an interactive prompt where you can select from supported AI coding agents:

* **Claude Code** - Artifacts in `.claude/` directory
* **Cursor** - Artifacts in `.cursor/rules/` directory
* **GitHub Copilot** - Artifacts in `.github/copilot-instructions.md`
* **Continue.dev** - Artifacts in `.continue/` directory
* **Junie** - Artifacts in `.junie/` directory
* **AGENTS.md** - Single `AGENTS.md` file at project root
* **GitLab Duo** - Artifacts in `.gitlab/` directory

The command auto-detects existing agent configurations in your project and pre-selects them. Your selection is saved to `packmind.json`.

<Tip>
  **Auto-detection** — If you already have agent configuration files (like
  `.cursor/` or `.claude/`), they will be automatically pre-selected when you
  run this command.
</Tip>

## Onboard Command

Scan your project and generate standards, commands, and skills based on detected patterns.

### When to Use Onboard

Use the onboard command when:

* You want to scan your project after running `init`
* You want to re-scan after project changes
* You want to regenerate project-specific content
* You want to scan a different directory

### Basic Usage

```bash theme={null}
packmind onboard
```

### Flags

| Flag           | Short | Description                                               |
| -------------- | ----- | --------------------------------------------------------- |
| `--path <dir>` | `-p`  | Specify a different project path to scan                  |
| `--dry-run`    | `-d`  | Preview without writing files                             |
| `--yes`        | `-y`  | Skip confirmation prompts                                 |
| `--push`       |       | Push generated standards and commands to Packmind backend |

**Examples:**

```bash theme={null}
# Scan a different directory
packmind onboard --path ./other-project

# Preview what would be generated
packmind onboard --dry-run
```

## Setup MCP Command

Configure MCP (Model Context Protocol) for your AI coding agents. This command automatically sets up the Packmind MCP server in your agents' configuration.

### Supported Agents

* **Claude Code** (`claude`)
* **Cursor** (`cursor`)
* **VS Code / GitHub Copilot** (`copilot`)

### Interactive Mode

Run without arguments to use interactive mode:

```bash theme={null}
packmind setup-mcp
```

This will:

1. Detect which AI agents are installed on your system
2. Present a selection prompt with detected agents pre-selected
3. Configure MCP for all selected agents

### Direct Mode

Specify target agents directly using the `--target` (or `-t`) flag:

```bash theme={null}
packmind setup-mcp --target claude
```

Configure multiple agents at once:

```bash theme={null}
packmind setup-mcp --target claude --target cursor
```

Or using the short form:

```bash theme={null}
packmind setup-mcp -t claude -t cursor -t copilot
```

<Tip>
  **Automatic Setup** — When you run `packmind login`, the setup-mcp command
  runs automatically after successful authentication.
</Tip>

## Install Command

Download commands, standards, and skills from packages to your local machine.

### List Available Packages

```bash theme={null}
packmind install --list
```

### View Package Details

```bash theme={null}
packmind install --show <package-slug>
```

### View Workspace Status

See an overview of all `packmind.json` files and their installed packages across your workspace:

```bash theme={null}
packmind install --status
```

**Example output:**

```
Workspace packages status

packmind.json                        Packages
-----------------------------------------------------------------
./packmind.json                      generic
./apps/api/packmind.json             nestjs
./apps/frontend/packmind.json        frontend

3 unique packages currently installed.
```

This is useful for:

* Understanding what packages are installed across a monorepo
* Identifying empty or misconfigured `packmind.json` files (shown as `<no packages>`)
* Getting a quick summary of unique packages in your workspace

### Install Packages

```bash theme={null}
packmind install <package-slug> [additional-package-slugs...]
```

**Example:**

```bash theme={null}
packmind install backend frontend
```

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

<Note>
  **Default skills included** — When you install packages, Packmind's default
  skills (including the `packmind-create-skill` skill) are automatically
  installed alongside your package contents.
</Note>

### Lock File (`packmind-lock.json`)

When you install or uninstall packages, the CLI generates a `packmind-lock.json` file alongside your `packmind.json`. This file records the exact versions of all installed artifacts.

### Recursive Install (Monorepos)

By default, `packmind install` (with no package slugs) finds all `packmind.json` files in your git repository and installs their configured packages. After installation, a summary shows how many distributions were notified to Packmind.

```bash theme={null}
packmind install
```

To scope the recursive install to a specific directory, use the `--path` option:

```bash theme={null}
packmind install --path apps/frontend
```

<Warning>
  The `-r` / `--recursive` flag is deprecated. Install is now recursive by
  default. Using the flag still works but will print a deprecation warning.
</Warning>

<Tip>
  **AI Agent Rendering** — The files created by the install 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](/administration/manage-ai-agents).
</Tip>

## Lint Command

<Info>
  **Enterprise Feature** — The lint command is only available in the
  **Enterprise** edition.
</Info>

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 Commands](/getting-started/gs-distribute) 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](/governance/distribution) to learn about this approach.

<Tip>
  **Priority** — When both local `packmind.json` files and deployments exist,
  the local configuration takes priority.
</Tip>

### Basic Usage

```bash theme={null}
packmind 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:

```bash theme={null}
packmind lint src/
```

```bash theme={null}
packmind lint /path/to/your/project
```

Lint a single file:

```bash theme={null}
packmind lint src/components/Button.tsx
```

When a single file is passed:

* The CLI verifies the file exists and exits with an error if not
* `.packmindignore` patterns are checked — if the file matches, it is skipped and the command exits with code 0
* If the file is not in scope for the requested rule or standard (i.e. its extension doesn't match the rule's configured languages), an informational message is logged and no violations are reported

### Limiting Scope with `--changed-files` and `--changed-lines`

When working on large codebases, you can focus the lint check on only the files or lines you've modified using the `--changed-files` and `--changed-lines` flags.

<Info>
  **Git Repository Required** — The `--changed-files` and `--changed-lines`
  flags requires your project to be in a Git repository.
</Info>

<Note>
  **Deprecated Option** — The `--diff` option is deprecated. Use
  `--changed-files` (equivalent to `--diff=files`) or `--changed-lines`
  (equivalent to `--diff=lines`) instead.
</Note>

**Check modified lines only:**

```bash theme={null}
packmind lint . --changed-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:**

```bash theme={null}
packmind lint . --changed-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:**

```bash theme={null}
# Make some changes to your code
git add .

# Check only what you changed
packmind lint . --changed-lines

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

### Output Formats

Choose between human-readable and IDE-friendly output:

```bash theme={null}
packmind 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.

### Filtering by Severity

Use the `--level` flag to filter which violations are displayed based on their severity:

```bash theme={null}
# Show only errors (suppress warnings)
packmind lint . --level error

# Show warnings and errors (everything)
packmind lint . --level warning
```

| Value     | What is displayed                    |
| --------- | ------------------------------------ |
| `error`   | Only error-level violations          |
| `warning` | All violations (warnings and errors) |

Without the `--level` flag, all violations are displayed regardless of severity.

<Tip>
  **CI/CD usage** — Use `--level error` in your CI pipeline to focus on blocking
  violations only, while still running `--level warning` (or no flag) during
  local development to see all feedback. See [Rule
  Severity](/linter/linter#rule-severity) for details on how severity affects
  exit codes.
</Tip>

## Skills Command

Manage skills in your Packmind organization. Skills are reusable knowledge packages that AI coding assistants can discover and use.

### Initialize Default Skills

```bash theme={null}
packmind skills init
```

This command installs Packmind's default skills locally, including:

* **packmind-create-skill** — A skill that guides you through creating new skills with AI assistance
* **packmind-create-command** — A skill that guides you through creating reusable commands with AI assistance
* **packmind-create-standard** — A skill for creating coding standards
* **packmind-onboard** — A skill for initializing Packmind in projects

After running this command, you can use these skills in your AI coding assistant:

* `/packmind-create-skill` - Create new skills
* `/packmind-create-command` - Create new commands
* `/packmind-create-standard` - Create new standards
* `/packmind-onboard` - Initialize Packmind in projects

<Tip>
  **Automatic installation** — Default skills are also installed automatically
  when you run `packmind init`, install a package with `packmind install`, or
  when packages are distributed to your repository via the web app.
</Tip>

### List Skills

```bash theme={null}
packmind skills list
```

This command displays all skills in your Packmind organization, showing:

* **Slug** — The skill identifier
* **Name** — The display name
* **URL** — Direct link to view the skill in the web app
* **Description** — What the skill does

**Example output:**

```
Available skills:

- packmind-create-skill
    Name: Create Skill
    URL: https://app.packmind.com/org/my-org/space/global/skills/packmind-create-skill/files
    Description: Guide for creating effective skills...

- my-custom-skill
    Name: My Custom Skill
    URL: https://app.packmind.com/org/my-org/space/global/skills/my-custom-skill/files
    Description: Custom skill for my project...
```

### Add a Skill

```bash theme={null}
packmind skills add <path>
```

**Arguments:**

* `<path>` - Path to the skill directory containing skill files

**Example:**

```bash theme={null}
packmind skills add ./my-skill
```

This uploads the skill to your Packmind organization, making it available for distribution to repositories.

When uploading a skill that already exists, Packmind automatically compares the content:

* If changes are detected, a new version is created
* If the content is identical, no new version is created

See [Skills Management](/concepts/skills-management) for details on versioning.

## Standards Command

Create and manage coding standards from the command line.

### List Standards

```bash theme={null}
packmind standards list
```

This command displays all standards in your Packmind organization, showing:

* **Slug** — The standard identifier
* **Name** — The display name
* **URL** — Direct link to view the standard in the web app
* **Description** — What the standard covers

**Example output:**

```
Available standards:

- error-handling
    Name: Error Handling
    URL: https://app.packmind.com/org/my-org/space/global/standards/abc123/summary
    Description: Ensure errors are handled predictably...

- typescript-conventions
    Name: TypeScript Conventions
    URL: https://app.packmind.com/org/my-org/space/global/standards/def456/summary
    Description: TypeScript coding conventions...
```

<Info>
  **Updating standards via CLI** — The CLI currently supports creating standards
  but not yet updating existing ones. To update a standard, use the web app or
  MCP server. CLI support for updating standards is coming in Q1 2026.
</Info>

### Create a Standard from a Playbook

```bash theme={null}
packmind standards create [file]
```

**Arguments:**

* `[file]` - Path to a JSON playbook file containing the standard definition (optional — reads from stdin if omitted)

**Examples:**

From a file:

```bash theme={null}
packmind standards create ./my-standard.json
```

From stdin:

```bash theme={null}
echo '{"name":"Error Handling","description":"...","scope":"All services","rules":[{"content":"Validate inputs at boundaries"}]}' | packmind standards create
```

Using a heredoc:

```bash theme={null}
packmind standards create <<'EOF'
{
  "name": "Error Handling",
  "description": "Ensure errors are handled predictably.",
  "scope": "All services",
  "rules": [{ "content": "Validate inputs at boundaries and fail fast" }]
}
EOF
```

This creates a new coding standard in your Packmind organization based on the playbook.

### Playbook File Format

The standard-playbook file is a JSON file with the following structure:

```json theme={null}
{
  "name": "Error Handling",
  "description": "Ensure errors are handled predictably with context and actionable feedback.",
  "scope": "Applies to all services and applications",
  "rules": [
    {
      "content": "Validate inputs at boundaries and fail fast"
    },
    {
      "content": "Preserve context when rethrowing errors",
      "examples": {
        "positive": "throw new PersistenceError('Save failed', { cause: e });",
        "negative": "throw new Error('Save failed');",
        "language": "TYPESCRIPT"
      }
    }
  ]
}
```

**Required fields:**

| Field         | Description                              |
| ------------- | ---------------------------------------- |
| `name`        | Standard name (displayed in the web app) |
| `description` | Context and purpose of the standard      |
| `scope`       | Where the standard applies               |
| `rules`       | Array of rules (at least one required)   |

**Rule fields:**

| Field      | Required | Description                                                                              |
| ---------- | -------- | ---------------------------------------------------------------------------------------- |
| `content`  | Yes      | Rule description (max \~25 words, starts with action verb like "Use", "Avoid", "Prefer") |
| `examples` | No       | Code examples showing correct and incorrect usage                                        |

**Example fields (when provided):**

| Field      | Description                                                       |
| ---------- | ----------------------------------------------------------------- |
| `positive` | Code snippet showing correct implementation                       |
| `negative` | Code snippet showing incorrect implementation                     |
| `language` | Programming language (e.g., `TYPESCRIPT`, `JAVASCRIPT`, `PYTHON`) |

<Tip>
  **Workflow tip** — Use this command when you have standards defined as files
  in your repository or want to create standards without the MCP server. Stdin
  support makes it easy to pipe JSON from scripts or AI agents.
</Tip>

## Commands Command

Create and manage reusable, multi-step workflow commands from the command line.

### List Commands

```bash theme={null}
packmind commands list
```

This command displays all commands in your Packmind organization, showing:

* **Slug** — The command identifier
* **Name** — The display name
* **URL** — Direct link to view the command in the web app

**Example output:**

```
Available commands:

- add-a-new-rest-endpoint
    Name: Add a New REST Endpoint
    URL: https://app.packmind.com/org/my-org/space/global/commands/abc123

- setup-database-migration
    Name: Setup Database Migration
    URL: https://app.packmind.com/org/my-org/space/global/commands/def456
```

<Info>
  **Updating commands via CLI** — The CLI currently supports creating commands
  but not yet updating existing ones. To update a command, use the web app. CLI
  support for updating commands is coming in Q1 2026.
</Info>

### Create a Command from a Playbook

```bash theme={null}
packmind commands create [file]
```

**Arguments:**

* `[file]` - Path to a JSON playbook file containing the command definition (optional — reads from stdin if omitted)

**Examples:**

From a file:

```bash theme={null}
packmind commands create ./setup-api-endpoint.json
```

From stdin:

```bash theme={null}
cat my-command.json | packmind commands create
```

Using a heredoc:

```bash theme={null}
packmind commands create <<'EOF'
{
  "name": "Add a New REST Endpoint",
  "summary": "Step-by-step guide for adding a new REST endpoint",
  "whenToUse": ["When adding a new API endpoint"],
  "contextValidationCheckpoints": ["Do you understand the business requirement?"],
  "steps": [{ "name": "Define the Route", "description": "Create the HTTP route" }]
}
EOF
```

This creates a new command in your Packmind organization based on the playbook.

### Playbook File Format

The command playbook file is a JSON file with the following structure:

```json theme={null}
{
  "name": "Add a New REST Endpoint",
  "summary": "Step-by-step guide for adding a new REST endpoint with validation, tests, and documentation",
  "whenToUse": [
    "When adding a new API endpoint to the backend service",
    "When extending existing API functionality",
    "When creating endpoints for frontend integration"
  ],
  "contextValidationCheckpoints": [
    "Do you understand the business requirement for this endpoint?",
    "Do you know the request and response data structures?",
    "Is the endpoint's purpose clear to all team members?"
  ],
  "steps": [
    {
      "name": "Define the Route",
      "description": "Create the HTTP route with appropriate method (GET, POST, PUT, DELETE) and path in your API configuration"
    },
    {
      "name": "Implement the Handler",
      "description": "Write the handler function that processes the request and calls the appropriate use case or service",
      "codeSnippet": "// Example Express handler\napp.post('/api/users', async (req, res) => {\n  const user = await userService.create(req.body);\n  res.status(201).json(user);\n});"
    },
    {
      "name": "Add Input Validation",
      "description": "Validate request parameters and body data before processing"
    },
    {
      "name": "Write Tests",
      "description": "Create unit and integration tests covering success and error scenarios"
    },
    {
      "name": "Update API Documentation",
      "description": "Document the endpoint with request/response examples and parameter descriptions"
    }
  ]
}
```

### Command Identification

When you create a command, Packmind automatically generates a **slug** from the command name:

* **Name** (provided by you): `"Add a New REST Endpoint"`
* **Slug** (auto-generated): `"add-a-new-rest-endpoint"`

The slug is used for:

* File naming: `.claude/commands/add-a-new-rest-endpoint.md`
* AI agent invocation: `/add-a-new-rest-endpoint`
* Command identification and distribution

If a command with the same slug already exists in your space, Packmind appends a counter (e.g., `add-a-new-rest-endpoint-1`) to ensure uniqueness.

**Required fields:**

| Field                          | Description                                              |
| ------------------------------ | -------------------------------------------------------- |
| `name`                         | Command name (displayed in the web app)                  |
| `summary`                      | What the command does and why it's useful                |
| `whenToUse`                    | Array of scenarios when this command applies             |
| `contextValidationCheckpoints` | Array of validation questions to clarify before starting |
| `steps`                        | Array of step objects (at least one required)            |

**Step fields:**

| Field         | Required | Description                                    |
| ------------- | -------- | ---------------------------------------------- |
| `name`        | Yes      | Step title (e.g., "Define the Route")          |
| `description` | Yes      | Clear instructions for what to do in this step |
| `codeSnippet` | No       | Optional code example demonstrating the step   |

<Tip>
  **Workflow tip** — Use this command when you have commands defined as files in
  your repository or want to create commands without the MCP server. Stdin
  support makes it easy to pipe JSON from scripts or AI agents. Commands are
  particularly useful for capturing multi-step development workflows that your
  team performs regularly.
</Tip>

## Packages Command

Create and manage packages from the command line.

### List Packages

```bash theme={null}
packmind packages list
```

This command displays all packages in your Packmind organization, showing:

* **Slug** — The package identifier
* **Name** — The display name

### Create a Package

```bash theme={null}
packmind packages create <name>
```

**Arguments:**

* `<name>` - Name of the package to create

**Options:**

| Flag            | Short | Description                |
| --------------- | ----- | -------------------------- |
| `--description` | `-d`  | Description of the package |

**Example:**

```bash theme={null}
packmind packages create "Backend Standards"
```

With a description:

```bash theme={null}
packmind packages create "Backend Standards" -d "Standards and commands for backend development"
```

This creates a new empty package in your Packmind organization. After creation, you can add commands, standards, and skills to the package through the web interface or by using the `packageSlugs` parameter when creating items via MCP.

### Package Identification

When you create a package, Packmind automatically generates a **slug** from the package name:

* **Name** (provided by you): `"Backend Standards"`
* **Slug** (auto-generated): `"backend-standards"`

The slug is used for:

* Package installation: `packmind install backend-standards`
* Package identification and distribution

If a package with the same slug already exists in your space, Packmind appends a counter (e.g., `backend-standards-1`) to ensure uniqueness.

### Add Items to a Package

```bash theme={null}
packmind packages add --to <package-slug> --standard <standard-slug>
packmind packages add --to <package-slug> --command <command-slug>
packmind packages add --to <package-slug> --skill <skill-slug>
```

**Options:**

| Flag         | Description                                |
| ------------ | ------------------------------------------ |
| `--to`       | Target package slug (required)             |
| `--standard` | Slug of the standard to add to the package |
| `--command`  | Slug of the command to add to the package  |
| `--skill`    | Slug of the skill to add to the package    |

**Examples:**

Add a standard to a package:

```bash theme={null}
packmind packages add --to backend --standard error-handling
```

Add a command to a package:

```bash theme={null}
packmind packages add --to backend --command create-api-endpoint
```

Add a skill to a package:

```bash theme={null}
packmind packages add --to backend --skill debugging-workflow
```

<Tip>
  **Workflow tip** — Use this command after creating standards, commands, or
  skills via CLI to organize them into packages. This is particularly useful
  when automating package management in scripts or CI/CD pipelines.
</Tip>

## Diff Command

Compare your local artifact files (standards, commands, skills) against the versions published in Packmind, and optionally propose your changes for team review.

### Preview Changes

```bash theme={null}
packmind diff
```

This compares your local files against the published versions and displays what has changed. No changes are submitted.

**Example output:**

```
Standard: Error Handling

  Rule (update)
  - Validate inputs at system boundaries and fail fast
  + Validate inputs at system boundaries, fail fast, and log the context

  Rule (add)
  + Preserve context when rethrowing errors

  Rule (delete)
  - Avoid swallowing exceptions silently
```

For each standard, the diff shows:

* **Rule (update)** — a rule that was modified (Packmind detects this automatically using similarity matching)
* **Rule (add)** — a new rule added locally
* **Rule (delete)** — a rule removed locally

### Submit Changes as Proposals

```bash theme={null}
packmind diff --submit
```

Submits your local changes as change proposals, which can be reviewed and accepted by your team in the Packmind web app.

Add an optional message to explain the intent behind your changes:

```bash theme={null}
packmind diff --submit -m "Improve error handling rules for better observability"
```

If you omit `-m`, Packmind opens your default editor so you can write the message interactively.

**Options:**

| Flag                  | Short | Description                                                       |
| --------------------- | ----- | ----------------------------------------------------------------- |
| `--submit`            |       | Submit detected changes as change proposals                       |
| `--message <text>`    | `-m`  | Message describing the intent behind the changes (max 1024 chars) |
| `--include-submitted` |       | Include already-submitted changes in the output                   |

### How Rule Updates Are Detected

When you modify a rule in a standard file, Packmind automatically determines whether the change is a rule update (the same rule was edited) or a separate deletion and addition (two unrelated rules). This keeps your change proposals clean and meaningful, showing reviewers exactly what was changed rather than an unrelated delete + add pair.

<Tip>
  **Requires a git repository** — The `diff` command requires your project to be
  in a git repository with a configured remote. Make sure you have run `packmind
      install` to set up your `packmind.json` before using `diff`.
</Tip>

## Update Command

Update the Packmind CLI to the latest version.

```bash theme={null}
packmind update
```

This checks for a newer version and updates the CLI in place:

* **Standalone executable** — Downloads the latest binary from GitHub and replaces the current executable automatically.
* **npm global install** — Runs `npm install -g @packmind/cli@latest` to update through npm.

**Example output:**

```
Current version: 1.2.0 (standalone executable)
New version available: 1.2.0 -> 1.3.0
Downloading packmind-cli-macos-arm64...
Downloaded successfully (12.4 MB)

Updated to v1.3.0
Binary location: /usr/local/bin/packmind
```

If you are already on the latest version:

```
Already up to date (v1.3.0)
```

<Tip>
  **Permission error on Linux/macOS** — If you see a permission denied error,
  run the command with `sudo`:

  ```bash theme={null}
  sudo packmind update
  ```
</Tip>

### Check for Updates Without Installing

Use the `--check` flag to see if a newer version is available without performing the update:

```bash theme={null}
packmind update --check
```

This is useful in CI/CD pipelines or scripts where you want to detect outdated CLI versions without automatically upgrading. The command exits with code `1` if a newer version is available, and code `0` if already up to date.

**Example:**

```bash theme={null}
if ! packmind update --check; then
  echo "A new version of packmind is available. Run 'packmind update' to upgrade."
fi
```

<Note>
  The `update` command is available for standalone executables and npm global
  installs only. If you manage the CLI through a local `package.json`, update it
  with `npm update @packmind/cli` instead.
</Note>

## Related Documentation

* [Create your first command](/getting-started/gs-create-command): Learn how to create commands with AI assistance
* [Packages Management](/concepts/packages-management): Learn about organizing commands, standards, and skills into packages
* [Linter: Automated Detection](/linter/linter): Learn about how detection programs work
* [Standards Management](/concepts/standards-management): Create rules and add code examples
* [Skills Management](/concepts/skills-management): Create and manage reusable skills