# LLM Provider Configuration Source: https://docs.packmind.com/administration/llm-configuration Configure your LLM (Large Language Model) provider to enable AI-powered features in Packmind, such as customizing standards and commands for AI Agents. ## Supported Providers Packmind supports the following LLM providers: | Provider | Description | | - | - | | **OpenAI** | OpenAI GPT models including GPT-4 and GPT-5 | | **Anthropic Claude** | Anthropic Claude models known for safety and helpfulness | | **Google Gemini** | Google's Gemini models with multimodal capabilities | | **Azure OpenAI** | Microsoft Azure-hosted OpenAI models | | **OpenAI-Compatible** | Any OpenAI-compatible API (Ollama, LM Studio, etc.) | ## Configuration via Web Interface The recommended way to configure your LLM provider is through the Packmind web interface: 1. Log in to Packmind as an administrator 2. Navigate to **Settings** > **AI** > **Provider** 3. Select your preferred provider from the dropdown 4. Fill in the required configuration fields 5. Save the configuration ## Model Selection Guidelines Packmind uses two model types: * **Primary Model**: Used for complex operations like generating detailed standards and commands. Choose a more capable model here. * **Fast Model**: Used for simpler operations where speed matters more than capability. Choose an economical model here. **Recommended configurations:** | Provider | Primary Model | Fast Model | | - | - | - | | OpenAI | `gpt-5.2` | `gpt-4.1-mini` | | Anthropic | `claude-sonnet-4-5-20250929` | `claude-haiku-4-5-20251001` | | Google Gemini | `gemini-3-pro-preview` | `gemini-2.5-flash` | ## Security Considerations * API keys are encrypted at rest in the database * Keys are never exposed in API responses after being saved * Use environment-specific API keys for different deployments * Rotate your API keys periodically * Monitor your API usage to detect any unauthorized access ## Troubleshooting ### Connection Test Fails 1. Verify your API key is correct and has not expired 2. Check that your network allows outbound connections to the provider's API 3. For Azure OpenAI, ensure the deployment name matches exactly 4. For local providers (Ollama, LM Studio), verify the server is running ### Model Not Found 1. Verify the model name is spelled correctly 2. For Azure OpenAI, use the deployment name, not the model name 3. For Ollama, ensure the model is pulled: `ollama pull ` 4. Check that your API key has access to the specified model ### Rate Limiting If you encounter rate limiting errors: 1. Consider using a lower-tier model for the Fast Model 2. Upgrade your API plan with the provider 3. Implement request queuing in high-traffic scenarios # Manage AI Agent Rendering Source: https://docs.packmind.com/administration/manage-ai-agents ## Overview Organization administrators can control which AI coding assistants receive your standards and commands when you distribute them to Git repositories. This allows you to distribute only the formats your team actually uses. Only users with **Admin** privileges can configure AI agent rendering. If you need to change this configuration, contact your organization administrator. ## Configuring AI Agents To configure which agents are enabled: 1. Go to **Settings** → **Distribution** → **Rendering** 2. Toggle on the agents you want to use 3. Click **Save Changes** When you distribute standards or commands, only the enabled agents will have their instruction files updated in your Git repositories. ## Available AI Agents | AI Agent | File Location | Can be Disabled? | | - | - | - | | **Packmind** | `.packmind/` | No (Required) | | **AGENTS.md** | `AGENTS.md` | Yes | | **GitHub Copilot** | `.github/` directory | Yes | | **Cursor** | `.cursor/` directory | Yes | | **Claude Code** | `.claude/` directory | Yes | | **Junie** | `.junie/guidelines.md` | Yes | | **GitLab Duo** | `.gitlab/duo/chat-rules.md` | Yes | | **Continue** | `.continue/rules/packmind/` | Yes | | **OpenCode** | `AGENTS.md`, `.opencode/` | Yes | | **Codex** | `AGENTS.md`, `.agents/` | Yes | | **Kiro** | `.kiro/` directory | Yes | The **Packmind** renderer cannot be disabled. It creates internal files in the `.packmind/` directory that are used by Packmind and other agents to function properly. ## What Happens When You Change Configuration * Changes apply immediately to all future distributions * Existing distributed files in your repositories are not affected * Only the selected agents will receive updates when you distribute standards or commands * The Packmind renderer always creates files regardless of your selection ## Learn More For detailed information about where standards and commands appear for each AI assistant and how to use them, see [Understanding Where Your Artifacts Appear](/concepts/artifact-rendering). # Manage Organizations Source: https://docs.packmind.com/administration/manage-organizations ## Overview Organizations in Packmind help you group your standards, commands, skills, and packages by team or project. Each user can belong to multiple organizations and switch between them as needed. When you first sign up for Packmind, you'll create your first organization. You can create additional organizations at any time. ## Creating a New Organization You can create a new organization at any point while using Packmind: 1. Click on the **organization name** in the top-left corner of the screen 2. Select **New organization** from the dropdown menu 3. Enter a name for your organization 4. Click **Create** to confirm Your new organization will be created and automatically selected as your active organization. ## Switching Between Organizations To switch to a different organization: 1. Click on the **organization name** in the top-left corner of the screen 2. Select the organization you want to switch to from the dropdown menu The application will immediately switch to the selected organization, and you'll see that organization's standards, commands, packages, and settings. All your work (standards, commands, skills, and packages) is organization-specific. When you switch organizations, you'll see different content and settings. ## Organization Settings Organization administrators have access to additional settings for managing their organization. See the following guides for specific administrative tasks: * [Managing Users](/administration/manage-users) - Invite users and manage roles * [Manage AI Agents](/administration/manage-ai-agents) - Configure AI agent access * [LLM Configuration](/administration/llm-configuration) - Configure language models * [Marketplace Governance](#marketplace-governance) - Curate Git repositories as Packmind-governed marketplaces Only users with **Admin** privileges can access organization settings. If you need administrative access, contact your organization administrator. ## Marketplace Governance Marketplace governance lets organization administrators curate a trusted set of plugin sources for their members. Once a marketplace is linked, every member of the organization can browse the marketplace and the plugins it exposes; only administrators can link or unlink. ### What is a marketplace? A **marketplace** is a Git repository registered at the organization level that exposes a marketplace descriptor. The descriptor declares the plugins the repository offers, and the coding agent it targets — **Claude Code** or **GitHub Copilot** — follows from which path holds it: | Descriptor path | Agent | | - | - | | `.claude-plugin/marketplace.json` | Claude Code | | `marketplace.json` (root) | Claude Code | | `.github/plugin/marketplace.json` | GitHub Copilot | A repository targets one agent or the other, never both. Packmind probes those paths in the order above and the first one it finds decides the marketplace's type, so the type is never guessed from the descriptor's contents and you don't pick it yourself when linking. Marketplaces are governance-only constructs: * **Admins** link and unlink marketplaces, and monitor their health. * **Members** browse the enrolled marketplaces and discover the plugins they expose. Marketplaces are **organization-scoped**. There is no per-user marketplace link — every member of the organization sees the same enrolled marketplaces. A repository linked as a marketplace is kept separate from repositories used for standard skill/command distribution. The same `(owner, repo)` pair cannot be linked as both a marketplace and a standard distribution target. ### Linking a marketplace Linking is an **admin-only** action. The denial is enforced server-side — hiding the UI is not sufficient, and non-admin API callers receive an HTTP 403. Marketplaces are linked through one of your organization's connected Git providers, so the repository can live behind authentication (private GitHub/GitLab org, internal SCM, etc.). 1. From the organization sidebar, open **Marketplaces** and click **Link a marketplace**. 2. In the drawer, pick one of your organization's connected Git providers. 3. Select the repository that hosts the marketplace descriptor. Packmind validates that the chosen repository exposes a valid descriptor before persisting the link, and records which agent it targets. Linking is restricted to organization administrators. Members who attempt to link via the API receive an HTTP 403 response. ### Health state semantics Every linked marketplace carries a health **state** that Packmind refreshes via a periodic reconciliation job. The current state is visible on each row of the marketplace list. | State | Meaning | | - | - | | **healthy** | The reconciliation job successfully re-fetched and re-validated the descriptor, and it still matches the one captured at link time. | | **drift** | The reconciliation job successfully re-fetched and re-validated the descriptor, but it has changed since the last run (plugins added, removed, edited). | | **unreachable** | The reconciliation job could not reach the repository or could not retrieve a parseable descriptor (network failure, repository removed, descriptor deleted). | | **bad\_format** | The descriptor was reachable but is missing or cannot be parsed — the marketplace contract is broken and an admin must fix it. | The initial state at link time is **healthy**. The state is refreshed on a periodic schedule (default: every 30 minutes) and the `lastValidatedAt` timestamp on the marketplace row is updated on every run. When a marketplace appears as **drift**, review the new descriptor before relying on the marketplace — plugins may have been added, removed, or modified upstream. ### Unlinking Unlinking is also an **admin-only** action. It severs Packmind governance over the marketplace but **never** touches the Git repository. When you unlink a marketplace: * The marketplace record is soft-deleted on the Packmind side. * The underlying marketplace-typed `GitRepo` record is soft-deleted alongside it. * The Git repository, its branches, and any in-flight pull requests are **left untouched** — Packmind performs no GitHub/GitLab mutation. Unlinking is a Packmind-side governance action only. If you need to remove the underlying repository, branches, or pull requests, do that on the Git platform itself — Packmind will not do it for you. To unlink: 1. Open the marketplace row in the **Marketplaces** list. 2. Click **Unlink** and confirm the action in the dialog. ### Errors and resolutions The table below maps the most common errors surfaced during link/unlink to the action that resolves them. | Error | When it appears | What to do | | - | - | - | | `MarketplaceAlreadyLinkedError` | `The marketplace {owner}/{repo} has already been linked to your organization` (HTTP 409). | Open the existing marketplace from the list instead of linking again. Unlink the existing entry first if you intend to re-link it. | | `MarketplaceDescriptorNotFoundError` | `No marketplace descriptor found in repository {owner}/{repo}. Looked for: .claude-plugin/marketplace.json, marketplace.json, .github/plugin/marketplace.json` (HTTP 400). | None of the descriptor paths above hold a file. Add one — `.claude-plugin/marketplace.json` for Claude Code, `.github/plugin/marketplace.json` for GitHub Copilot — then retry. Verify you selected the correct branch. | | `UnknownMarketplaceDescriptorError` | `No registered marketplace descriptor parser recognised the provided content` (HTTP 400). | The descriptor's contents match neither the Claude Code nor the GitHub Copilot format. Check it against the schema for the agent you are targeting. | | `MarketplaceDescriptorParseError` | A parser claimed the descriptor but failed to parse or validate it (HTTP 400). | Inspect the descriptor for malformed JSON or missing required fields, fix it on the repository side, then retry. | | `MarketplaceNotFoundError` | `Marketplace with id "{marketplaceId}" was not found` (HTTP 404). | The marketplace was already unlinked or never existed. Refresh the list to see the current state. | The contract message *"The marketplace / has already been linked to your organization"* is stable and safe to surface verbatim to end users. # Manage Users Source: https://docs.packmind.com/administration/manage-users ## Overview Organization administrators can manage team members and control access for their organization. Only users with **Admin** privileges can manage users. If you need to invite users or manage roles, contact your organization administrator. To learn how to create or switch between organizations, see [Managing Organizations](/administration/manage-organizations). ## User Roles Packmind has two user roles: * **Admin**: Full access to organization settings, including user management and Git repository configuration * **Member**: Standard user access without administrative privileges ## Inviting New Users To invite new members to your organization: 1. Go to **Settings** → **Users** 2. Click **Invite Users** 3. Enter email addresses 4. Select the role for the invited users (Admin or Member) 5. Click **Send Invitations** Invited users receive a link that allows them to create their account and join your organization. ### Email Delivery When you invite users: * **With SMTP configured**: Invitation emails are sent automatically to the invited users. See [SMTP Configuration](/getting-started/gs-install-self-hosted#smtp-configuration) for setup instructions. * **Without SMTP configured**: The invitation email content and invitation link are logged in Packmind's logs. Self-hosted administrators can retrieve these links from the logs and share them manually with invited users. ## Managing User Roles Admins can change roles for other users in the organization: 1. Go to **Settings** → **Users** 2. Find the user in the list 3. Click **Change user role** from the actions column 4. Select the new role (Admin or Member) 5. Click **Save** to confirm **Note**: You cannot change your own role. Changes take effect immediately. ## Removing Users To remove a user from your organization: 1. Go to **Settings** → **Users** 2. Find the user in the list 3. Click **Remove** from the actions column 4. Confirm the removal Removed users will lose access to the organization and its resources. # Understanding Where Your Artifacts Appear Source: https://docs.packmind.com/concepts/artifact-rendering After distributing your standards, commands, and skills through Packmind, they appear in specific locations in your Git repositories. Each AI coding assistant reads from its own designated folder or file, allowing it to apply your team's guidelines automatically. ## Overview When you distribute a package containing standards, commands, and skills: 1. **Standards** are automatically loaded by your AI assistant when you're coding. They guide the AI to follow your team's conventions without any action on your part. 2. **Commands** are instructions you can run on-demand when you need to perform a specific task. You invoke them manually when needed. 3. **Skills** are knowledge packages that AI agents discover and use based on the task at hand. They're triggered automatically by the AI when relevant. Your organization administrator controls which AI assistants receive updates in **Settings** → **Distribution** → **Rendering**. See [Manage AI Agent Rendering](/administration/manage-ai-agents) for details. ## Where Standards Appear Standards are placed in specific folders that your AI assistant monitors. Once distributed, they're automatically applied when the AI generates or reviews code. | AI Assistant | Where Standards Appear | | - | - | | Claude Code | `.claude/rules/packmind/` folder | | Cursor | `.cursor/rules/packmind/` folder | | GitHub Copilot | `.github/instructions/` folder | | Continue | `.continue/rules/packmind/` folder | | GitLab Duo | `.gitlab/duo/chat-rules.md` file | | Junie | `.junie/guidelines.md` file | | AGENTS.md | `AGENTS.md` file (in repository root) | | OpenCode | `AGENTS.md` file (in repository root) | | Codex | `AGENTS.md` file (in repository root) | | Kiro | `.kiro/steering/` folder | Standards work automatically—you don't need to do anything special to activate them. Your AI assistant reads them and applies the guidelines when generating code. ### How Single-File Rendering Works Some AI assistants (**AGENTS.md**, **GitLab Duo**, **Junie**, **OpenCode**, **Codex**) use a single shared file rather than a dedicated folder for standards. Because you may want to add your own instructions to these files, Packmind uses HTML comment markers to delineate its managed section: ``` ... Packmind-managed content ... ``` Packmind only updates the content **between** these markers. You are free to add your own content before or after them — it will be preserved across distributions. If the markers don't exist yet (for example, in a brand-new file), Packmind appends the section at the end of the file. ### Standard Scopes and File Patterns When you define a standard, you can specify a **scope** using glob patterns (like `**/*.spec.ts` for test files or `src/components/**/*.tsx` for React components). For AI assistants that support native integration (**Claude Code**, **Cursor**, **GitHub Copilot**, **Continue**, and **Kiro**), these glob patterns are included in the rendered files. The AI assistant will automatically apply the standard only to files matching the specified patterns. For other AI assistants (GitLab Duo, Junie, AGENTS.md), standards are included in a single file without scope filtering—the AI applies them based on context. For **Kiro**, the scope is rendered as `inclusion: fileMatch` with a `fileMatchPattern` list. The Kiro IDE honours it and applies the standard only to matching files. The Kiro **CLI** ignores steering inclusion modes and loads every file in `.kiro/steering/`, so scoped standards are not narrowed there. ## Where Commands Appear and How to Use Them Commands are placed in specific locations, but unlike standards, you need to invoke them manually when you want to use them. | AI Assistant | Where Commands Are Rendered | How to Use | | - | - | - | | Claude Code | `.claude/commands/` folder | Type `/command-name` in chat | | Cursor | `.cursor/commands/` folder | Type `/command-name` in chat | | GitHub Copilot | `.github/prompts/` | Type `/command-name` in chat | | Continue | `.continue/prompts/` | Type `/command-name` in chat | | GitLab Duo | Not rendered (use source) | Execute @.packmind/commands/command-name.md | | Junie | Not rendered (use source) | Execute @.packmind/commands/command-name.md | | AGENTS.md | Not rendered (use source) | Execute @.packmind/commands/command-name.md | | OpenCode | `.opencode/commands/` folder | Type `/command-name` in chat | | Codex | Not rendered (use source) | Execute @.packmind/commands/command-name.md | | Kiro | Not rendered (use source) | Execute @.packmind/commands/command-name.md | ### Using Slash Commands (Claude Code, Cursor, GitHub Copilot, Continue, OpenCode) For AI assistants with native slash command support (**Claude Code**, **Cursor**, **GitHub Copilot**, **Continue**, and **OpenCode**), commands are rendered in dedicated folders and can be invoked using slash commands: ``` /create-new-use-case ``` The AI assistant will recognize the command and execute the instructions defined in it. ### Direct Source File Invocation (GitLab Duo, Junie, AGENTS.md, Codex, Kiro) For AI assistants without native command rendering (**GitLab Duo**, **Junie**, **AGENTS.md**, **Codex**, and **Kiro**), commands are not rendered in agent-specific files. Instead, you must reference the source command file directly from the `.packmind/commands/` folder: ``` Execute @.packmind/commands/create-new-use-case.md ``` The AI assistant will read the command file from the `.packmind/commands/` folder and follow its instructions. All commands are **user-invoked**—they only run when you explicitly call them. This is different from standards, which are applied automatically by the AI. ## Where Skills Appear Skills are folders of instructions, scripts, and resources that AI agents can discover and use to perform tasks more accurately. Unlike commands which require explicit invocation, skills are **agent-discovered**—the AI automatically loads relevant skills based on the task at hand. | AI Assistant | Where Skills Appear | | - | - | | GitHub Copilot | `.github/skills/{skill-slug}/SKILL.md` | | Claude Code | `.claude/skills/{skill-slug}/SKILL.md` | | Cursor | `.cursor/skills/{skill-slug}/SKILL.md` | | GitLab Duo | `.gitlab/duo/skills/{skill-slug}/SKILL.md` | | OpenCode | `.opencode/skills/{skill-slug}/SKILL.md` | | Codex | `.agents/skills/{skill-slug}/SKILL.md` | | Kiro | `.kiro/skills/{skill-slug}/SKILL.md` | Skills contain YAML frontmatter with metadata (name, description, license, compatibility, allowed-tools) followed by the skill instructions. Skills are currently available for GitHub Copilot, Claude Code, Cursor, GitLab Duo, OpenCode, Codex, and Kiro. Other AI assistants do not support skill rendering. ## The Source Files Regardless of which AI assistant you use, Packmind always creates source files in the `.packmind/` folder: * **Standards**: `.packmind/standards/` folder * **Commands**: `.packmind/commands/` folder * **Skills**: `.packmind/skills/` folder These source files are the single source of truth. The files in AI assistant-specific folders (like `.claude/` or `.cursor/`) are generated from these sources during distribution. ## Troubleshooting ### I don't see my commands available with slash commands **Solution**: Slash commands (`/command-name`) are only supported by Claude Code, Cursor, GitHub Copilot, Continue, and OpenCode. For other AI assistants, reference the command file directly using "Execute @.packmind/commands/command-name.md". ### My standards aren't being applied **Solution**: 1. Verify your organization has enabled the AI assistant in **Settings** → **Distribution** → **Rendering** 2. Make sure you've distributed the package containing the standards 3. Check that the standard files exist in the appropriate folder for your AI assistant ### I can't find the command files **Solution**: 1. Ensure you've distributed the package containing the commands 2. Check the `.packmind/commands/` folder for the source files 3. For Claude Code, Cursor, GitHub Copilot, Continue, or OpenCode: Verify the AI assistant-specific folder exists (e.g., `.cursor/commands/`) 4. For GitLab Duo, Junie, AGENTS.md, Codex, or Kiro: Commands are not rendered separately—use the files directly from `.packmind/commands/` ### The AI assistant isn't following my standards **Solution**: 1. Check that the standard scope (file patterns) matches the files you're working with 2. Verify the standard was distributed to the correct AI assistant 3. Try referencing the standard explicitly in your prompt if needed ### I can't find my skills **Solution**: 1. Skills are only rendered for GitHub Copilot, Claude Code, Cursor, GitLab Duo, OpenCode, Codex, and Kiro 2. Check the `.packmind/skills/` folder for the source files 3. For GitHub Copilot: Check `.github/skills/{skill-slug}/SKILL.md` 4. For Claude Code: Check `.claude/skills/{skill-slug}/SKILL.md` 5. For Cursor: Check `.cursor/skills/{skill-slug}/SKILL.md` 6. For GitLab Duo: Check `.gitlab/duo/skills/{skill-slug}/SKILL.md` 7. For Kiro: Check `.kiro/skills/{skill-slug}/SKILL.md` ## Related Documentation * [Manage AI Agent Rendering](/administration/manage-ai-agents) - Configure which AI assistants receive your artifacts * [Distribute Artifacts](/governance/distribution) - Learn how to distribute packages to repositories * [Standards Management](/concepts/standards-management) - Create and manage coding standards * [Commands Management](/concepts/commands-management) - Create and manage reusable commands * [Skills Management](/concepts/skills-management) - Create and manage reusable skills # Commands: automate repetitive tasks Source: https://docs.packmind.com/concepts/commands-management ## What are Commands? Commands are one of three artifact types in Packmind, alongside [standards](/concepts/standards-management) and [skills](/concepts/skills-management). In teams using AI coding assistants, sharing and reusing prompts that work is often tedious. A Packmind **Command** is an executable, step-by-step guide that tells the AI assistant exactly how to perform a development task so your team's practices are applied consistently and reproducibly. Commands are repeatable and predictable instruction patterns that can be applied to achieve a specific outcome. Examples of commands can be: * Create or update domain model and the SQL schema, including database migrations * Add a new use case in a business domain ## Creating Commands Commands can be created in two ways: 1. **Through the web app** — Create commands directly in the Packmind interface 2. **Through AI assistants** — Use the `/packmind-update-playbook` skill for AI-guided command creation ### Creating Commands in the Web App To create a command directly in the Packmind web app: 1. Navigate to **Commands** in the main menu 2. Click **Create** 3. Fill in the command details: * **Name**: A descriptive name for the command * **Content**: The instructions in Markdown format 4. Click **Save** to create the command Use the web app when you want to quickly create or edit commands manually. Use the `/packmind-update-playbook` skill when you want AI assistance in structuring commands from your development history. ### Creating Commands with AI Assistants You can create commands using the `/packmind-update-playbook` command in your AI coding assistant. Simply type: ``` /packmind-update-playbook create a command to add a new endpoint in the API. ``` The AI agent will automatically follow the **command creation workflow**: 1. Identifies the development process you want to capture 2. Structures it into clear, actionable steps with context validation checkpoints 3. Defines specific "when to use" scenarios 4. Adds optional code examples to demonstrate each step This command is automatically available when you run `packmind skills init` or distribute packages to your repository. ### Best Practices for Command Creation To get the best results, provide rich context to your AI agent: * **After completing a task**: When you've accomplished a series of tasks in a session with your AI Agent, ask it to create a command based on what you've done ``` Synthesize the steps we followed to create a new use case and create a Packmind command based on this ``` * **From Git history**: A commit or pull request can reflect a command. Ask your agent to analyze commits or a Pull Request URL ``` Create a command by analyzing the changes in pull request #123 ``` * **From existing code**: Provide files as context to extract patterns ``` Create a command for adding a new API endpoint based on @routes/users.ts and @controllers/UserController.ts ``` The workflow ensures your command includes: * Clear step-by-step instructions * Context validation checkpoints (questions to ask before starting) * Usage scenarios (when this command applies) * Optional code snippets for each step ## Updating Commands **Updating commands** is possible from the web app, on the dedicated section of the commands. You can also use the `/packmind-update-playbook` skill to have your agents update an existing command: ``` /packmind-update-playbook Update the create-api-endpoint command to use the newly defined guard system. ``` Alternatively, you can manually edit the files corresponding to the command and use the `playbook` command of the cli to submit them: ``` packmind playbook add .claude/commands/create-api-endpoint.md packmind playbook submit ``` Use `--no-review` to trigger a [direct update](/playbook-maintenance/updating-your-playbook#direct-updates). Omit `--no-review` to use the [change proposals](/playbook-maintenance/change-proposals) system and get validation of your changes. ## Commands Versions Every time you update a command, this creates a new version. This keeps track of the history of your changes, and it's useful to keep track of which versions are currently distributed to Git repositories. ## Command Identification Each command has three identifiers: | Identifier | Example | Purpose | | - | - | - | | **Name** | `"Add a New REST Endpoint"` | User-facing display name in the web app | | **Slug** | `"add-a-new-rest-endpoint"` | URL-safe identifier used for invocation and file naming | | **ID** | `550e8400-e29b-41d4-a716-446655440000` | Internal database identifier | The **slug** is automatically generated from the name and used throughout the system. If you create multiple commands with similar names in the same [space](/concepts/spaces), Packmind appends numbers to keep slugs unique (e.g., `"add-api-endpoint"`, `"add-api-endpoint-1"`). ## How to Use Commands After Distribution Unlike standards (which are applied automatically), commands are **user-invoked**—you run them when you need them. Commands are identified and invoked using their **slug** (the auto-generated URL-safe name). ### Using Slash Commands (Claude Code, Cursor, GitHub Copilot, Continue, OpenCode) For AI assistants with native slash command support, type `/` followed by the command slug: ``` /add-a-new-rest-endpoint ``` The AI assistant will recognize the command by its slug and execute its instructions. ### Manual Invocation (GitLab Duo, Junie, AGENTS.md, Codex, Kiro) For AI assistants without native slash command support, reference the command file by its slug: ``` Execute @.packmind/commands/add-a-new-rest-endpoint.md ``` The AI assistant will read the command file and follow its instructions. For detailed information about where commands appear for each AI assistant and all invocation methods, see [Understanding Where Your Artifacts Appear](/concepts/artifact-rendering). # Packages: organize your artifacts Source: https://docs.packmind.com/concepts/packages-management ## What are Packages? A **Package** is a curated collection of commands, standards, and skills grouped together. Packages organize your artifacts in a way that matches how your team actually works—whether by technology, domain, team, or architectural layer. Instead of managing dozens of individual items, packages let you group related artifacts and distribute them as a single unit. ## How to Distribute Packages There are two ways to distribute packages to your team: 1. **Install locally via CLI** - Download packages directly to your local machine (no Git required) 2. **Distribute to Git repositories** - Push packages to your repositories (requires Git configuration) These are alternative distribution methods—you can choose the approach that fits your workflow. You don't need to use both. ## Creating Packages ### Via Web Interface 1. Navigate to **Packages** in the Packmind UI 2. Click **Create Package** 3. Provide a name and description 4. Select commands, standards, and skills to include — only items that belong to no package can be picked here, see [Choosing Items](#choosing-items-when-you-create-or-edit-a-package) 5. Save the package ### Via CLI Create an empty package from the command line: ```bash theme={null} packmind packages create "My Package" -d "Package description" ``` See the [CLI documentation](/tools/cli#packages-command) for details. ### Adding Items to Packages An item belongs to a single package. Putting an item in a package takes it out of the one it was in. **Via Web Interface** — from the list of standards, commands, or skills: 1. Select one or more items 2. Click **Manage packages** 3. Under **Move to a package**, pick the destination Each package in that list says what picking it would do. **Moves 2, Adds 1** means two of the selected items come from another package and one is in no package yet; hover the count to see which items those are. You can do the same for a single item from its own page, using the package control at the top: it reads **In 1 package**, or **Add to a package** when the item belongs to none. **Via CLI** — use `packmind packages add` for an item that is in no package, and `packmind packages move` to take one from another package: ```bash theme={null} packmind packages add --to backend --standard error-handling packmind packages move --to backend --command create-api-endpoint ``` `packmind packages add` refuses an item that already belongs to another package and prints the `move` command to run instead. Moving an item out of a package that is distributed to repositories or marketplaces removes it from them. Packmind asks you to confirm first and names the places affected: anyone working there loses the item at their next sync. ### Choosing Items When You Create or Edit a Package The **Standards**, **Commands**, and **Skills** dropdowns of a package form only offer items that belong to no package. An item another package holds is greyed out and labelled with the package holding it — move it from the item's own page, or from the list of items, to bring it here. Items already in the package you are editing stay selectable, so you can always take one out. ### Removing Items from a Package An item that belongs to no package is not installed or distributed anywhere, so Packmind always tells you where the item still lives after a removal. * **Via Web Interface** — click the **×** next to a package name, either on the item's row in a list or in the **In these packages** section of the **Manage packages** panel * **Via CLI** — use `packmind packages remove`: ```bash theme={null} packmind packages remove --from backend --command create-api-endpoint ``` ## Using Packages Once you've created packages, you can distribute them using either of these methods: ### Option 1: Install Locally Download package content directly to your machine using the CLI: ```bash theme={null} packmind install backend-api frontend-web ``` This creates the appropriate files for your AI coding assistant on your local machine without requiring Git. See the [CLI documentation](/tools/cli#install-command) for details. ### Option 2: Distribute to Repositories Push packages to your Git repositories through the web interface: 1. Navigate to **Packages** 2. Select packages to distribute 3. Choose target paths 4. Click **Distribute** All commands, standards, and skills in the package are committed together to your repository. **Default skills included** — All distributions automatically include Packmind's default skills (such as `packmind-update-playbook` for creating and updating playbook artifacts). These are added alongside your package contents. Learn more in the [Distribution documentation](/governance/distribution). ## Package Versions A package can be released under a version. A **release** is an immutable snapshot of the package: it records the package's name and description, and pins the exact version of every command, standard, and skill the package contains at the moment you create it. Nothing changes a release afterwards—publishing a newer version of a component, renaming the package, or removing a component leaves it untouched. Open a package and a bar under its name says which version you are reading. It reads **Unreleased**—the package as it stands, the only reading with no version number—or **Not released yet** when the package has never been released. **Distribution always sends current content** — A release names a state, it doesn't change what gets distributed. When you distribute a package or install it with the CLI, it always includes the latest version of each command, standard, and skill it contains. To see which repositories have outdated versions, check the [distribution overview](/governance/distribution). ### Creating a Release 1. Navigate to **Packages** and select your package 2. Click **Create a release**, beside **Unreleased** in the bar under the package name 3. Enter a version number as `X.Y.Z`, or click one of the three suggested increments 4. Submit the form The field is pre-filled with the next patch version, and only the three suggested increments are accepted. After `0.1.0`, those are `0.1.1`, `0.2.0`, and `1.0.0`. A package's first release is pre-filled with `0.1.0`. A version that isn't accepted stays in the field so you can correct it. A version that isn't written as `X.Y.Z` is refused with `Version must follow X.Y.Z`, and a version lower than or equal to the current one with `Version must be greater than 1.2.0`, naming the current version. Suffixes such as `1.2.0-beta-2` aren't accepted. Any member of the **space** can create a release. ### When You Can Create a Release **Create a release** appears once the package has changed since its last release. Any one of these counts as a change: * A command, standard, or skill in the package has a newer version than the release pinned * The package's name or description was edited * A component was added to or removed from the package When there is nothing to release, the action isn't there: the package is identical to its last release, or it holds no component at all. Nothing else in the bar changes. ### Reading an Earlier Version Open the menu on **Unreleased** to see every release of the package, newest first, each with the day it was cut. Select one and the package is shown as that version left it: the components it pinned, at the versions it pinned them, including components deleted since. The reading is read-only—a release never changes—so the controls that write the package leave while you are on it. The version you are reading is part of the address, so a link to `1.1.0` opens on `1.1.0` for whoever you send it to. Select **Unreleased** in the same menu, or the link beside the list, to come back to the package as it stands. # Skills: reusable knowledge for AI agents Source: https://docs.packmind.com/concepts/skills-management ## What are Skills? Skills are reusable knowledge packages that AI coding agents can discover and use to perform tasks more accurately. Based on Claude Code skills and Agents skills specifications, they provide specialized capabilities that agents can trigger based on the task at hand. Unlike standards (which apply automatically) and commands (which require explicit invocation), skills are **agent-discovered**—the AI automatically loads relevant skills based on context and triggers defined in the skill. ## Skill Structure A skill is a folder containing at minimum a `SKILL.md` file, plus optional supporting files. ### Required: SKILL.md The `SKILL.md` file contains YAML frontmatter followed by Markdown instructions: ```markdown theme={null} --- name: 'skill-name' description: 'Brief description of what this skill does' --- # Skill Name Instructions for when and how AI agents should use this skill. ``` **Frontmatter fields:** | Field | Required | Description | | - | - | - | | `name` | Yes | Unique identifier for the skill | | `description` | Yes | Brief explanation of what the skill does | | `license` | No | License type (e.g., MIT, Apache-2.0) | | `compatibility` | No | Which AI agents support this skill | | `allowed-tools` | No | List of tools the skill may use | | `disallowed-tools` | No | List of tools the skill is not allowed to use (Claude Code only) | | `metadata` | No | Additional custom metadata | ### Optional Supporting Files Skills can include additional files alongside `SKILL.md`: * **Templates** — Boilerplate code, configuration files, or scaffolding * **Scripts** — Automation scripts the skill may reference or execute * **Resources** — Documentation, examples, or reference materials * **Subdirectories** — Organize complex skills with multiple related files All files in the skill directory are packaged together when you upload the skill. ## Creating Skills The easiest way to create a skill is using the `/packmind-update-playbook` skill in your AI coding assistant. Simply type: ``` /packmind-update-playbook create a Packmind skill for ``` The AI agent will guide you through creating a skill with proper structure and documentation. You can also import skills you already have. From the web app, go to **Skills**, open **Create** and choose **Import skills**, then drag or choose a folder — see [Importing skills from the web app](/getting-started/gs-create-skill#how-to-import-skills-from-the-web-app). Alternatively, you can create skills manually through the CLI by uploading a skill directory: ```bash theme={null} # Create your skill directory with SKILL.md mkdir my-skill # Add your SKILL.md and any supporting files # ... # Upload to Packmind packmind playbook add ./my-skill packmind playbook submit --no-review ``` Use `--no-review` to trigger a [direct update](/playbook-maintenance/updating-your-playbook#direct-updates). Omit `--no-review` to use the [change proposals](/playbook-maintenance/change-proposals) system and get validation of your changes. For a complete walkthrough, see [Create Your First Skill](/getting-started/gs-create-skill). ## Updating Skills When you upload a skill that already exists in your organization, Packmind automatically handles versioning: 1. **Content comparison** — The CLI compares the uploaded content against the latest version 2. **New version created** — If any content differs (changes to `SKILL.md`, new files, modified scripts, or updated assets), a new version is created 3. **No duplicate versions** — If the content is identical to the current version, no new version is created To update an existing skill, simply upload it again: ```bash theme={null} packmind playbook add ./my-skill packmind playbook submit --no-review ``` Use `--no-review` to trigger a [direct update](/playbook-maintenance/updating-your-playbook#direct-updates). Omit `--no-review` to use the [change proposals](/playbook-maintenance/change-proposals) system and get validation of your changes. ### Viewing Version History You can view all versions of a skill in the Packmind web app: 1. Navigate to **Skills** in the main menu 2. Click on the skill you want to inspect 3. View the **Version history** section to see all versions Each version includes a timestamp, allowing you to track when changes were made. ## Editing a Skill You can edit a skill's Markdown content directly from the Packmind web app, without going through the CLI. ### What You Can Edit * **SKILL.md body** — the instructions section is editable * **Supporting Markdown files** — any other `.md` file included in the skill is editable * **Non-Markdown files** — templates, scripts, and other non-`.md` files remain read-only * **SKILL.md frontmatter** — fields like `name`, `description`, `license`, and `compatibility` are read-only and are not shown in the edit view ### Who Can Edit Editing is restricted to: * Organization admins * Space admins * The skill's original creator Other space members can view the skill but cannot edit it. ### How to Edit 1. Navigate to **Skills** in the main menu 2. Click on the skill you want to edit 3. Select the file you want to change from the **Files** list 4. Make your changes and save Content can't be empty and can't exceed 300,000 characters. This limit applies whether you edit from the web app, upload via the CLI, or apply a submitted change. ### Versioning Saving your edit creates a new version of the skill, attributed to you as the editor—even if you weren't the skill's original creator. If you save without making any actual changes, no new version is created. ## Deleting Skills You can delete skills that are no longer needed through the Packmind web app. ### Delete a Single Skill 1. Navigate to **Skills** in the main menu 2. Click on the skill you want to delete 3. Click the **Delete** button 4. Confirm the deletion in the dialog ### Delete Multiple Skills To delete multiple skills at once: 1. Navigate to **Skills** in the main menu 2. Select the skills you want to delete using the checkboxes 3. Click **Delete selected** 4. Confirm the batch deletion in the dialog **Impact on packages** — When you delete a skill that's included in one or more packages, those packages will be updated. You'll need to redistribute the affected packages to remove the skill from your repositories. ## Viewing Skills Access your skills through the Packmind web app: 1. Navigate to **Skills** in the main menu 2. Browse the list of available skills 3. Click a skill to view its details The skill details view shows: * **Description** — What the skill does * **Files** — All files included in the skill * **Version history** — Track changes over time * **Packages** — Which packages include this skill ## Skills in Packages Skills can be added to packages alongside commands and standards. To add a skill to a package: 1. Go to **Packages** in the web app 2. Edit an existing package or create a new one 3. Select skills to include 4. Save the package A skill belongs to a single package, so the form only offers skills that belong to none. To take a skill from another package, open it from **Skills**, use the package control at the top of its page, and pick the new package — the skill joins it and leaves the old one. See [Packages Management](/concepts/packages-management#adding-items-to-packages). When you distribute a package, all included skills are deployed together with your other artifacts. **Default skills included** — When packages are distributed (via the web app push strategy or CLI install), Packmind's default skills are automatically included. This ensures the `packmind-update-playbook` skill is always available for creating and updating playbook artifacts with AI assistance. ## Where Skills Appear After Distribution After distributing a package containing skills, they appear in specific locations based on the AI assistant: | AI Assistant | Where Skills Appear | | - | - | | GitHub Copilot | `.github/skills/{skill-slug}/SKILL.md` | | Claude Code | `.claude/skills/{skill-slug}/SKILL.md` | | Cursor | `.cursor/skills/{skill-slug}/SKILL.md` | | GitLab Duo | `.gitlab/duo/skills/{skill-slug}/SKILL.md` | | OpenCode | `.opencode/skills/{skill-slug}/SKILL.md` | | Codex | `.agents/skills/{skill-slug}/SKILL.md` | | Kiro | `.kiro/skills/{skill-slug}/SKILL.md` | The source files are always stored in `.packmind/skills/` regardless of which AI assistants are enabled. Skills are currently available for Claude Code, Cursor, GitHub Copilot, Codex, OpenCode, GitLab Duo and Kiro. Other AI assistants do not support skill rendering. For complete details on where artifacts appear, see [Understanding Where Your Artifacts Appear](/concepts/artifact-rendering). ## How Skills Differ from Commands and Standards | Aspect | Standards | Commands | Skills | | - | - | - | - | | **Activation** | Automatic | User-invoked | Agent-discovered | | **Purpose** | Enforce guidelines | Execute tasks | Provide capabilities | | **Creation** | CLI or Web UI | CLI or Web UI | CLI or Web UI | | **Format** | Rules with examples | Step-by-step instructions | SKILL.md + resources | * **Standards** are coding guidelines that AI assistants follow automatically * **Commands** are tasks you invoke explicitly with slash commands * **Skills** are knowledge packages that AI agents discover and use as needed ## Related Documentation * [Create Your First Skill](/getting-started/gs-create-skill) — Step-by-step guide to creating skills * [CLI Reference](/tools/cli#skills-command) — Skills CLI command details * [Packages Management](/concepts/packages-management) — Organize and distribute artifacts * [Understanding Where Your Artifacts Appear](/concepts/artifact-rendering) — See where skills are rendered # Spaces: organize your playbook Source: https://docs.packmind.com/concepts/spaces **Enterprise Feature** — This functionality is only available in the **Enterprise** version of Packmind. ## What are Spaces? Spaces let you organize your playbook into distinct areas that reflect how your team works. A Space can represent a topic, a team, a programming language, a functional scope, or a technical scope — for example, "Backend", "React Frontend", "Security", or "Data Pipeline". Instead of managing all artifacts in a single flat list, Spaces give structure to your standards, commands, and skills so each group sees what is relevant to them. ## The Global Space Every organization comes with a built-in **Global** space. It has special rules: * It **cannot be deleted** * Its **visibility cannot be changed** * Every members of the organization belong to this space The Global space is a good home for organization-wide conventions that apply to everyone. ## Space Types Spaces have two visibility levels: | Type | Visibility | Joining | | - | - | - | | **Open** | Visible to everyone in the organization | Anyone can browse and join via the sidebar | | **Private** | Hidden from non-members | Must be added by a space administrator | A space's visibility can be changed later — an open space can become private, and a private space can become open. Only **organization administrators** can make a space open. (The Global space is an exception — its visibility cannot be changed.) Space names must be **unique** within an organization. ## Creating a Space Any organization member can create a **private** space. Only **organization administrators** can create an **open** space. Click **Browse** in the sidebar to see all available spaces, then click **New** to create one. Provide a name and choose a visibility level (open or private). ## Roles Within a Space Each space has its own set of roles, separate from [organization roles](/administration/manage-users): | Action | Space Admin | Space Member | Organization Admin | | - | - | - | - | | Add/remove members | Yes | No | Yes | | Change member roles | Yes | No | Yes | | Delete the space | Yes | No | Yes | The creator of a space becomes its first administrator. Space roles are independent from organization roles. A user can be an administrator in one space and a regular member in another. ## Leaving a Space Any member can leave a space on their own at any time — except the Global space, which cannot be left. ## Deleting a Space Only **space administrators** and **organization administrators** can delete a space. Deleting a space **permanently removes all its artifacts** — standards, commands, and skills contained in that space are deleted. This action cannot be undone. The Global space cannot be deleted. ## Spaces and the CLI ### Package slug prefixing When your organization uses multiple spaces, package slugs are prefixed with the space slug using `@space/package` notation: ```bash theme={null} packmind install @backend/standards @frontend/react ``` ### Access warnings during install If your `packmind.json` references packages from spaces you do not currently have access to, the `install` command displays a warning. However, this does **not** affect your existing configuration — files from those packages are **not removed**, they simply will not be updated. To resolve access issues: * **Open spaces** — join the space via the sidebar in the Packmind app * **Private spaces** — ask a space administrator or a colleague to add you ## Related Documentation * [Packages Management](/concepts/packages-management) — group artifacts into packages within a space * [Distribute Artifacts](/governance/distribution) — distribute packages from spaces to your repositories * [Manage Users](/administration/manage-users) — organization-level roles and permissions * [CLI Documentation](/tools/cli) — CLI commands including install with space-prefixed packages # Standards: enforce your coding guidelines Source: https://docs.packmind.com/concepts/standards-management ## Why Standards Matter with AI Agents Standards are one of three artifact types in Packmind, alongside [commands](/concepts/commands-management) and [skills](/concepts/skills-management). Context engineering is key to making the most of AI coding assistants. Standards are guidelines that drive the output of agents, ensuring they generate code that follows your team's conventions and best practices. Many teams struggle with documentation that nobody reads or maintains—wikis and Markdown files that become outdated quickly. With AI coding assistants, this problem becomes even more critical. Standards make your written documentation useful again by providing consistent, actionable guidance that AI agents can follow automatically. ## Understand Standards and Rules A standard is an agreed-upon, documented set of rules or criteria that ensures consistent, compatible, and high-quality code across your team. Here is a basic example of a standard: **Standard**: Back-end unit tests **Rules for this standard**: * Use assertive names in test names (`it("returns ..."` instead of `it("should return")`) * Structure tests with the AAA pattern * Single expect per test ## Create Standards with AI Agents You can create standards using the `/packmind-update-playbook` skill in your AI coding assistant. Simply type: ``` /packmind-update-playbook create a Packmind standard about unit tests with Jest ``` Or use a natural language prompt like: *"Create a Packmind standard 'Unit tests with Jest' and extract coding rules by analyzing the file @test.spec.ts"* The AI agent will automatically follow a **guided workflow** to ensure high-quality standards: 1. Gather context from your codebase and iterate with you on the draft 2. Create the standard with rules and code examples For more details, see the [Create Your First Standard](/getting-started/gs-create-standard) guide. ## Create Standards Through UI Go to the **Standards** menu and create your first standard. The description area supports Markdown so you can give more context about it. Add your first rules, ideally with one clear detailed sentence. The *scope* let you define files and folders patterns where the standard applies. For instance, you may want to use `**/*.spec.ts` if your standard is related to tests. You can update your standard later to add and remove rules. Each rule can be documented with code examples as well. ## Standards Versions Every time you update a standard, this creates a new version. This keeps track of the history of your changes, and it's useful to keep track of which versions are currently distributed to Git repositories. You can submit local changes to your standards using: ```shell theme={null} packmind playbook add packmind playbook submit ``` Use `--no-review` to trigger a [direct update](/playbook-maintenance/updating-your-playbook#direct-updates). Omit `--no-review` to use the [change proposals](/playbook-maintenance/change-proposals) system and get validation of your changes. ## Where Standards Appear After Distribution Once you distribute a package containing standards, they appear in specific locations in your repository depending on which AI assistants your organization has enabled. Standards are automatically loaded by your AI assistant—you don't need to do anything special to activate them. For detailed information about where standards appear for each AI assistant, see [Understanding Where Your Artifacts Appear](/concepts/artifact-rendering). # CLI Installation & Setup Source: https://docs.packmind.com/getting-started/gs-cli-setup ## Overview The Packmind CLI is your primary tool for managing standards, commands, and skills. This guide will help you install and authenticate the CLI. **The installed command is `packmind`** — Earlier versions installed it as `packmind-cli`. That name still works for now, but it is deprecated and will be removed in a future release, so point any scripts or CI jobs at `packmind`. ## 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. Sets up your PATH environment variable Simply copy the provided command and paste it into your terminal. The script handles everything automatically. **Why this is recommended** — The one-click install eliminates manual steps by combining installation and authentication in a single command. ### Alternative: npm Package **Node.js 22 or higher required**. **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 login ``` 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-cli ``` The Homebrew formula is still named `packmind-cli`, and it installs the executable under that name. If `packmind` is not found after a Homebrew install, use `packmind-cli`. ### 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 ``` **Choosing an Installation Method** — Use **one-click install** for the simplest experience with automatic authentication. 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. ## 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 ``` ### Verify Authentication Check your current authentication status: ```bash theme={null} packmind whoami ``` This displays: * Connected host * Organization name * User name * Credential expiration status * Where your credentials come from (environment variable or credentials file) ### API Key Authentication (Alternative) You can authenticate using the `PACKMIND_API_KEY` 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` environment variable with your API key: ```bash theme={null} export PACKMIND_API_KEY="your-api-key-here" ``` To make this permanent, add it to your shell configuration file (`~/.bashrc`, `~/.zshrc`, etc.). ## Initialize Your Project Once you're authenticated, the first command to run inside your project is `packmind init`. This sets up Packmind for the repository and must be run before any onboarding or artifact generation. From the root of your project (which must be a Git repository), run: ```bash theme={null} packmind init ``` This will: * Prompt you to select which AI coding agents you use (Claude Code, Cursor, GitHub Copilot, etc.) * Save your selection to a `packmind.json` file at the project root * Install Packmind's default skills (including `packmind-onboard` and `packmind-update-playbook`) into the appropriate directories for your selected agents See the [Init Command](/tools/cli#init-command) reference for the full output and details. ## Next Steps Now that you have the CLI installed, authenticated, and your project initialized, you can create your first standards and commands: ### Quick Start: Run `/packmind-onboard` The fastest way to get started is to use the `/packmind-onboard` command in your AI coding assistant. This will guide your AI agent to: 1. Analyze your codebase automatically 2. Identify coding patterns and conventions 3. Generate standards and commands based on what it finds 4. Create or select a package to organize them Simply type in your AI assistant: ``` /packmind-onboard ``` The AI agent will walk you through the entire process interactively. ### Create Individual Artifacts You can also create standards, commands, and skills individually using the skill `packmind-update-playbook`. This skill guides your AI agent through a structured creation process. ### Learn More * **[Onboarding Guide](./gs-onboarding)** — Detailed guide on the onboarding process * **[CLI Reference](/tools/cli)** — Explore all available CLI commands Need help? Run `packmind --help` to see all available commands and options. # Create your first command Source: https://docs.packmind.com/getting-started/gs-create-command In teams using coding assistants, sharing and reusing *prompts that work* is often tedious. A Packmind **Command** is an executable, step-by-step guide that tells the AI assistant exactly how to perform a development task so your team's practices are applied consistently and reproducibly. **Examples** * “Add a new REST endpoint” — steps to define the route, implement the handler, add input validation, write tests, and update API docs. * “Set up a CI pipeline for a project” — steps to configure the workflow, run lint/tests/build on each push/PR, and report status checks. ## How to You can create commands using the `/packmind-update-playbook` skill in your AI coding assistant. 1. Open your IDE and your coding assistant in **agentic mode**. 2. For this demo, we will create a **language-agnostic command**. (You can also target a specific language or framework.) 3. Type this command: ``` /packmind-update-playbook create a Packmind command to add a new endpoint to our API ``` Or use a natural language prompt: ```text theme={null} Analyze our codebase and create a Packmind command to add a new endpoint to our API. ``` **Guided Creation** — The `/packmind-update-playbook` skill provides step-by-step guidance through the entire creation process, ensuring your command is well-structured and reusable. ### How it works The AI agent will automatically follow the **command creation workflow** which guides it through: 1. **Understanding the process** - The agent identifies the development process you want to capture as a command 2. **Structuring the command** - The agent breaks down the process into clear, actionable steps with: * **When to use** scenarios - Specific situations where the command applies * **Context validation checkpoints** - Questions to clarify before implementing * **Step-by-step instructions** - Atomic, repeatable actions with optional code examples 3. **Finalization** - Once structured properly, the agent creates the command in Packmind Your new command will be available in the Packmind web app, in the **Commands** panel. The workflow ensures commands are well-structured and reusable by enforcing clear steps, validation checkpoints, and usage scenarios. This makes them effective for AI agents and team members alike. ## Tips The quality of the generated command depends mostly on the level of detail you provide. When capturing a **Command**, you can, for example: * **Use the current conversation** **Example** ```text theme={null} /packmind-update-playbook Create a Packmind command for adding a new endpoint based on your last suggested changes. ``` * **Mention example files or directories** **Example** ```text theme={null} /packmind-update-playbook Using the file `MyPageFile.tsx`, create a Packmind command for bootstrapping a new page in the frontend. ``` * **Use a Git commit diff** **Example** ```text theme={null} /packmind-update-playbook Read commit abcd123 and create a command for migrating an Angular component to React. ``` ## What Makes a Good Command * **Clear purpose** — The command name and summary clearly explain what it accomplishes * **Realistic scenarios** — The "When to use" section covers actual situations your team encounters * **Validation checkpoints** — Questions clarify prerequisites and assumptions * **Actionable steps** — Each step is specific and can be completed independently * **Helpful examples** — Code snippets demonstrate what to do, not just explain it # Create your first skill Source: https://docs.packmind.com/getting-started/gs-create-skill Skills are reusable knowledge packages that AI coding agents can discover and use to perform tasks more accurately. Unlike commands (which you invoke explicitly) or standards (which apply automatically), skills are **agent-discovered**—the AI automatically loads relevant skills based on the task at hand. **Looking for inspiration?** Check out the [awesome-claude-skills](https://github.com/ComposioHQ/awesome-claude-skills/) repository for a curated list of community skills you can use as examples or starting points. Learn more about how skills work in the [Skills Management](/concepts/skills-management) section. ## Prerequisites * The CLI must be installed: see [CLI Installation](/tools/cli#installation) * You must be authenticated: run `packmind login` ## Understanding the Skill Format Skills follow the [Agent Skills specification](https://agentskills.io/home), an open format for giving agents new capabilities and expertise. A skill is a folder containing at minimum a `SKILL.md` file, plus optional supporting files like templates, scripts, and resources. For details on the SKILL.md format, frontmatter fields, and best practices, refer to the [Agent Skills specification](https://agentskills.io/home). ## Create a Skill Using the AI Agent The easiest way to create a skill is using the `/packmind-update-playbook` skill with your AI coding assistant. ### Create Your Skill Invoke the `/packmind-update-playbook` skill in your AI coding assistant: ``` /packmind-update-playbook create a Packmind skill for bootstrapping a new page in the frontend ``` The assistant will guide you through: 1. **Defining the skill purpose** — Describe what capability you want to provide 2. **Identifying triggers** — Specify when the AI should activate this skill 3. **Planning resources** — Determine if you need scripts, templates, or references 4. **Generating the skill** — Create the `SKILL.md` and supporting files 5. **Validating** — Check the skill follows the specification After the assistant generates your skill, you can test it locally before uploading. ## What Makes a Folder Importable Packmind treats any folder that directly contains a `SKILL.md` file as a skill. Supporting files and subfolders — templates, scripts, references — come along with it and keep their place inside the skill. For a skill to be accepted, its `SKILL.md` needs frontmatter with: * a **name** in lowercase, using hyphens instead of spaces (for example `code-review`) * a **description** saying what the skill does ## How to Import Skills from the Web App You can import skills without leaving your browser: 1. Navigate to **Skills** in the main menu 2. Open **Create** and choose **Import skills** (on an empty Skills page, use the **Import** button on the "Import your skills" card) 3. Drag a folder onto the panel, or choose one with **Choose folder** Packmind lists every skill it finds in the folder. If you point it at a parent folder such as `.claude/skills`, all the skills inside are listed at once. 4. Review the list — any skill that cannot be imported says why on its own line 5. Select **Import** Skills are imported one at a time, and each row shows its own result. A skill that fails does not stop the others: when the import finishes, you get a summary such as "3 imported, 1 failed", and the failed skill keeps its explanation so you can fix it and try again. Importing from the web creates the skills directly. It does not go through [change proposals](/playbook-maintenance/change-proposals). ### Why a Skill Might Be Refused * **A skill with that name already exists** — rename your folder, or edit the existing skill instead * **`SKILL.md` is missing** — the folder is not a skill; check you selected the right one * **The frontmatter is invalid** — the name or description does not meet the requirements above * **A file is too large** — single files and whole skills are both capped at 10 MB ## How to Upload a Skill to Packmind Once you have a skill folder ready, upload it to Packmind using the CLI: ```bash theme={null} packmind playbook add ./my-skill packmind playbook submit --no-review ``` Use `--no-review` to trigger a [direct update](/playbook-maintenance/updating-your-playbook#direct-updates). Omit `--no-review` to use the [change proposals](/playbook-maintenance/change-proposals) system and get validation of your changes. The CLI will upload the skill to your Packmind organization and display a confirmation. ### Uploading Multiple Skills at Once `playbook add` takes as many folders as you like, so a collection of skills goes up in one pair of commands: ```bash theme={null} packmind playbook add .claude/skills/*/ packmind playbook submit --no-review ``` If one of the folders cannot be staged, the others still are: the command reports which one failed and how many were staged, so you can fix that one and add it on its own. The same applies when submitting. If a skill's name is already taken, it is skipped and stays staged while the rest are submitted — rename it and run `packmind playbook submit --no-review` again to finish the job. ## View Your Skill After uploading, your skill appears in the Packmind web app: 1. Navigate to **Skills** in the main menu 2. Find your skill in the list 3. Click to view details, including files and version history ## Distribute Your Skill Once created, add your skill to a package to distribute it to repositories: 1. Go to **Packages** in the web app 2. Edit an existing package or create a new one 3. Add your skill to the package 4. Distribute the package to your repositories After distribution, the skill appears in: * `.claude/skills/{skill-slug}/SKILL.md` for Claude Code * `.cursor/skills/{skill-slug}/SKILL.md` for Cursor * `.github/skills/{skill-slug}/SKILL.md` for GitHub Copilot See [Understanding Where Your Artifacts Appear](/concepts/artifact-rendering) for details. ## Tips * **Keep skills focused** — Each skill should address a specific capability or workflow * **Write clear triggers** — Describe precisely when the AI should activate the skill * **Include examples** — Show expected inputs and outputs where applicable * **Test locally first** — Verify your SKILL.md renders correctly before uploading * **Browse community skills** — Explore [awesome-claude-skills](https://github.com/ComposioHQ/awesome-claude-skills/) for real-world examples and inspiration * **Read the specification** — Check the [Agent Skills specification](https://agentskills.io/home) for the complete format details # Create your first standard Source: https://docs.packmind.com/getting-started/gs-create-standard > A standard is an agreed-upon, documented set of rules or criteria that ensures consistent, compatible, and high-quality results across people, systems, or products. Aligning a team on standards—and following them—is hard. Many teams end up with wikis and Markdown files that nobody reads or maintains. With AI coding assistants, this problem becomes even more critical. Let’s see how we can make written documentation useful again with **Packmind**. Read more about the anatomy of a Packmind standard in the [dedicated section](/concepts/standards-management). ## Create a standard from your codebase You can create standards using the `/packmind-update-playbook` skill in your AI coding assistant. 1. Open your IDE and your coding assistant in **agentic mode**. 2. For this demo, we will create a language-agnostic standard. (You can also target a specific language or framework.) 3. Type this command: ``` /packmind-update-playbook create a Packmind standard about error handling ``` Or use a natural language prompt: ``` Analyze our codebase and create a Packmind standard about error handling. ``` ### How it works The AI agent will automatically follow the **standard creation workflow** which guides it through: 1. **Understanding your request** - The agent clarifies what standard you want to create and gathers appropriate context from your codebase 2. **Drafting the standard** - The agent creates a draft with name, description, and rules, iterating with you for feedback 3. **Finalization** - Once you're satisfied, the agent validates and creates the standard in Packmind Your new standard will be available in the Packmind web app, in the **Standards** panel. The workflow ensures consistent, high-quality standards by guiding the AI through best practices. You can provide feedback at any step, and the agent will refine the standard before submitting it. ## Create a standard with a coding agent When using a coding agent like Claude Code, you can invoke the `/packmind-update-playbook` skill to get guided assistance through the entire standard creation process. ### Using the skill 1. Open your coding agent (e.g., Claude Code) 2. Type `/packmind-update-playbook` followed by a description of the standard you want to create 3. The agent will analyze your codebase and iterate with you on the draft The agent will guide you through: 1. **Understanding your needs** — Clarifying what problem the standard solves and where it applies 2. **Writing rules** — Helping you craft clear, actionable rules following best practices 3. **Review** — Showing you the complete standard for approval 4. **Submission** — Creating the standard via the CLI The skill workflow is interactive and iterative. The agent will ask clarifying questions and help you refine your rules before creating the standard. ## Create a standard from the CLI You can also create standards directly using the Packmind CLI with a markdown file. ```bash theme={null} packmind playbook add .packmind/standards/my-standard.md packmind playbook submit --no-review ``` The markdown file should follow this structure: ```markdown theme={null} # A description of the standard (not mandatory) ## Scope **/\*.spec.ts, **/\*.test.ts - some rule that the agent should follow - another rule the agent should follow ``` The optional `## Scope` section holds the glob patterns the standard applies to, so your coding assistants only load it for matching files. Write globs rather than prose, separated by commas on one line or one bullet per pattern. Leave the section out for a standard that applies everywhere. The standard markdown should be located in a directory where instructions are available. Such directories include:
  • `.packmind/standards`
  • `.claude/rules`
  • `.cursor/rules`
  • `.github/instructions`
 ## Create a standard from the web app 1. Go to the **Standards** panel. 2. Click to create a new standard. 3. Fill in the following fields: * **Name** — a short title that explains the topic (e.g., “Frontend code conventions”, “DDD architecture”). * **Description** — context and benefits, for both coding assistants *and* developers. * **Rules** — a list of issues to avoid and coding rules to follow so the code complies with the standard. ### Example ```text theme={null} **Standard**: Error Handling **Description**: Ensure errors are handled predictably, with context, safety, and actionable feedback. Non-goals: don't use exceptions for control flow; don't log the same error at multiple layers; don't expose stack traces or internals in user-facing messages. **Checklist for reviews**: validated inputs; no empty catch; structured errors; cause preserved; safe logs; careful retries; actionable responses. **Scope**: Applies to all services, CLIs, UIs, and libraries. **Rules** 1) Validate inputs at boundaries; fail fast Bad (JavaScript): // UI handler submit(order); // accepts anything; crashes deeper Good (JavaScript): import { z } from "zod"; const Order = z.object({ id: z.string().min(1), items: z.array(z.string()).nonempty() }); const parsed = Order.safeParse(payload); if (!parsed.success) { throw new ValidationError("Invalid order", { issues: parsed.error.issues }); } submit(parsed.data); 2) Avoid swallowing errors; surface or handle them explicitly Bad (JavaScript): try { processPayment(tx); } catch (e) { // ignored; system appears "successful" } Good (JavaScript): try { await processPayment(tx); } catch (e) { if (e instanceof PaymentGatewayError) { logger.warn("Payment failed", { txId: tx.id, code: e.code }); throw new PaymentFailed("Could not process payment", { cause: e }); } throw e; // unknown error, bubble up } 3) Preserve context when rethrowing Bad (JavaScript): try { await repo.save(user); } catch (e) { throw new Error("Save failed"); // loses original cause } Good (JavaScript): class PersistenceError extends Error { constructor(message, options) { super(message, options); this.name = "PersistenceError"; } } try { await repo.save(user); } catch (e) { throw new PersistenceError("Save failed: User", { cause: e }); } 4) Use structured, domain-specific error types Bad (JavaScript): throw new Error("Not found"); Good (JavaScript): class NotFoundError extends Error { constructor(kind, key, options) { super(`${kind} not found`, options); this.name = "NotFoundError"; this.kind = kind; this.key = key; } } throw new NotFoundError("User", userId); 5) Log safely and meaningfully (no secrets; include identifiers) Bad (JavaScript): console.error("Auth failed for", credentials.password); // leaks secret Good (JavaScript): logger.error("Auth failed", { userId, ip, reason: "invalid_credentials" }); // no secret/PII 6) Retry deliberately with backoff only for safe, transient operations Bad (JavaScript): // Blind retry of a non-idempotent call for (let i = 0; i < 5; i++) { await chargeCard(request); // may double-charge } Good (JavaScript): const sleep = (ms) => new Promise(r => setTimeout(r, ms)); for (let attempt = 0; attempt < 3; attempt++) { try { const res = await fetch(url, { method: "GET" }); // idempotent if (!res.ok) throw new Error(`HTTP ${res.status}`); break; } catch (e) { if (attempt === 2) throw new CacheUnavailable("Timed out", { cause: e }); await sleep(2 ** attempt * 200); // exponential backoff } } 7) Return actionable messages to callers; hide internals Bad (JavaScript/JSON): { "error": "TypeError: Cannot read properties of undefined (reading 'email') at UserService.js:142:17" } Good (JavaScript/JSON): { "error": { "code": "USER_NOT_FOUND", "message": "The user does not exist.", "requestId": "c1a9..." } } ``` # Distribute standards, commands, and skills Source: https://docs.packmind.com/getting-started/gs-distribute This guide shows you how to install your **Standards**, **Commands**, and **Skills** locally using the Packmind CLI, making them available to your AI coding assistant. This approach downloads content directly to your local machine without requiring Git configuration. ## Create your first package Before distributing your artifacts, organize them into **Packages**. A package is a curated collection of commands, standards, and skills grouped together—for example, "Frontend Guidelines" or "Backend API Standards". Packages make it easy to distribute related guidelines as a single unit. **To create a package:** 1. Navigate to **Packages** in the Packmind UI 2. Click **Create Package** 3. Provide a name and description 4. Select commands, standards, and skills to include 5. Save the package You can organize packages by technology, domain, team, or architectural layer—whatever matches how your team works. For more details on managing packages, see the [Packages Management](/concepts/packages-management) documentation. ## Install packages with CLI **API Key Required** — The install command requires a valid API key to authenticate with Packmind. See the [CLI documentation](/tools/cli#authentication) for setup instructions. Use the Packmind CLI to install packages locally: **List available packages:** ```bash theme={null} packmind packages list ``` **View package details:** ```bash theme={null} packmind packages show ``` **Install one or more packages:** ```bash theme={null} packmind install [additional-package-slugs...] ``` This downloads all commands, standards, and skills from the specified packages and creates the appropriate files for your AI coding assistant. **Example - First installation:** ```bash theme={null} packmind install backend frontend ``` When you run `install` for the first time, it creates a `packmind.json` file in the current directory that tracks which packages are installed. Subsequent runs of `packmind install` (without arguments) will automatically install all packages listed in this file. **Example - Update from packmind.json:** ```bash theme={null} packmind install ``` This installs all packages defined in your `packmind.json` file. For detailed CLI usage, see the [CLI documentation](/tools/cli). ## Understanding packmind.json The `packmind.json` file is automatically created in your directory when you first run `packmind install` with package names. This file tracks which packages are installed locally, making it easy to keep your standards and commands up to date. ### File Structure The file has a simple JSON structure: ```json theme={null} { "packages": { "backend": "*", "frontend": "*", "security": "*" } } ``` Each package slug maps to a version number. Currently, all packages use `"*"` which means "latest version". ### How It Works **First Installation:** When you run `packmind install ` for the first time, the CLI: 1. Downloads the specified packages 2. Creates a `packmind.json` file in the current directory 3. Adds the installed packages to the file **Subsequent Installations:** When you run `packmind install` (without package names), the CLI: 1. Reads the `packmind.json` file 2. Installs all packages listed in the file 3. Updates your local standards and commands to the latest versions **Adding More Packages:** You can add more packages to an existing installation: ```bash theme={null} packmind install additional-package ``` This merges the new package with your existing `packmind.json` configuration. ### Managing packmind.json Manually You can edit the `packmind.json` file directly to add or remove packages. **To add a package manually:** 1. Open `packmind.json` 2. Add the package slug to the `packages` object: ```json theme={null} { "packages": { "backend": "*", "frontend": "*", "new-package": "*" } } ``` 3. Run `packmind install` to download the new package **To remove a package with the CLI:** Use the `uninstall` command (aliased as `remove`) with one or more package slugs: ```bash theme={null} packmind uninstall [additional-package-slugs...] ``` For example: ```bash theme={null} packmind uninstall backend ``` This removes the packages from `packmind.json` and deletes the files that were generated for them. **To remove a package manually:** 1. Open `packmind.json` 2. Remove the package slug from the `packages` object 3. Run `packmind install` to update your local files Removal is driven by the `packmind-lock.json` lock file, which records every file Packmind generated during installation. Because the lock file tracks files for all coding assistants, cleanup is agent-agnostic: it covers every agent's artifacts — `CLAUDE.md`, `AGENTS.md`, GitHub Copilot (`.github/copilot-instructions.md`), Cursor (`.cursor/rules/`), and others — so you no longer need to delete leftover files by hand. ### Using Multiple packmind.json Files You can run `packmind install` in different directories within your project, and each directory will have its own `packmind.json` file with its own set of packages. This is useful for: * **Monorepos**: Different packages or applications can have different standards * **Layered architectures**: Frontend and backend directories can have separate guidelines * **Team boundaries**: Different teams working in different directories can maintain their own standards **Example directory structure:** ``` my-project/ ├── packmind.json # Root-level packages (e.g., general coding standards) ├── frontend/ │ └── packmind.json # Frontend-specific packages └── backend/ └── packmind.json # Backend-specific packages ``` Each `packmind.json` file operates independently. By default, running `packmind install` (without package names) walks the entire directory tree starting from where you run it, updating every `packmind.json` it finds in that directory and its sub-directories. To limit the scope to a specific directory (and its direct sub-directories only), pass the `--path` (`-p`) option: ```bash theme={null} packmind install --path frontend ``` ## Alternative: Install globally for Claude Code If you use Claude Code and want a package available across every project on your machine — not just one repository — you can run `packmind install` inside your `~/.claude` directory. The CLI detects this and switches to a home-install mode that renders artifacts directly into `~/.claude/{skills,rules,commands}/...`, skips the agent prompt, and avoids creating a `.packmind/` mirror in your home folder. See [Install Globally for Claude Code](/tools/cli#install-globally-for-claude-code-claude) for the full benefits and behavior. ## Alternative: Distribute to Git repositories Instead of pulling locally, you can distribute packages directly to your Git repositories. This pushes standards and commands as files that are committed to your codebase. To learn about distributing to Git repositories, see the [Distribution documentation](/governance/distribution). ## Use your artifacts When you prompt your coding assistant, **Standards** and **Commands** are automatically included in its context. For complex tasks, the context can grow large, and the generated code may stop following your standards and commands. If this happens, re-add the `.packmind` directory to the agent's context and try again. # Use Packmind Cloud Source: https://docs.packmind.com/getting-started/gs-install-cloud ## Overview Packmind Cloud is a fully managed service that allows you to use Packmind without managing any infrastructure. Simply sign up and start using the platform immediately. During sign-up, you'll create your first organization. You can create additional organizations or switch between them at any time. See [Managing Organizations](/administration/manage-organizations) for more details. ## Availability Packmind Cloud is currently available at [https://app.packmind.ai](https://app.packmind.ai) (EU region). **US region will come soon.** ## Security & Privacy For comprehensive information about data handling, security measures, AI integration, and compliance, please see our [Security & Privacy documentation](/security/security-privacy). ## Next Steps After creating your Packmind Cloud account: 1. **[Install the CLI](./gs-cli-setup)** - Set up the Packmind CLI and authenticate with your account 2. **[Start Onboarding](./gs-onboarding)** - Scan your codebase to create your first standards # Install Packmind on your server Source: https://docs.packmind.com/getting-started/gs-install-self-hosted Find how to deploy Packmind using Docker Compose or Kubernetes, and how to customize the setup. For comprehensive information about security, data ownership, and privacy in self-hosted deployments, please see [Security & Privacy (Self-Hosted)](/security/security-privacy-self-hosted). ## With Docker Compose For Linux and MacOS users, run this script to create a `./packmind` folder with a Docker Compose setup inside: ```bash theme={null} mkdir packmind && \ cd packmind && \ curl -fsSL -o install.sh https://raw.githubusercontent.com/PackmindHub/packmind/refs/heads/main/dockerfile/prod/setup-packmind-compose.sh && \ chmod +x install.sh && \ ./install.sh ``` Once this command is executed, Packmind is now available at [http://localhost:8081/](http://localhost:8081/), and you can start using it right away. There are no default credentials. When accessing Packmind for the first time, you must complete the sign-up process to create your first organization and user account. See [Managing Organizations](/administration/manage-organizations) for more details about creating and switching organizations. Update later with `docker compose pull && docker compose up -d`. ## With Helm on Kubernetes Get started on the [Helm Chart GitHub repository](https://github.com/PackmindHub/packmind-ai-helm-chart) to deploy Packmind on Kubernetes. ## Connect your LLM (Optional but important) Connecting a LLM offers a better experience when distributing your standards and commands in your Git Repositories, while it's *not mandatory* and you can use Packmind without this. Packmind supports multiple AI providers: **OpenAI**, **Anthropic Claude**, **Google Gemini**, **Azure OpenAI**, and **OpenAI-Compatible** providers. See [LLM Configuration](/administration/llm-configuration) for full details on configuring each provider. The Docker Compose template includes OpenAI configuration by default. To use Docker Compose with OpenAI, update the `docker-compose.yml` file: ```yaml theme={null} x-openai-config: &openai-config OPENAI_API_KEY: ``` Restart then with: ```bash theme={null} docker compose up -d ``` ## Add custom CA certificates (Docker Compose) If your infrastructure uses self-signed certificates or custom Certificate Authorities (CA), you can configure Packmind to trust them: 1. Create a `certs` directory next to your `docker-compose.yml`: ```bash theme={null} mkdir certs ``` 2. Place your CA certificate(s) in PEM format as `certs/ca-bundle.pem`: ```bash theme={null} # For a single certificate cp your-ca-cert.pem certs/ca-bundle.pem # For multiple certificates, combine them cat cert1.pem cert2.pem > certs/ca-bundle.pem ``` 3. Edit `docker-compose.yml` and uncomment the certificate lines in the `api` service: ```yaml theme={null} api: environment: NODE_EXTRA_CA_CERTS: /ca-certs/ca-bundle.pem # Uncomment this line volumes: - ./certs/ca-bundle.pem:/ca-certs/ca-bundle.pem:ro # Uncomment these 2 lines ``` 4. Restart the services: ```bash theme={null} docker compose up -d ``` ## Enable social login with WorkOS (Optional) Packmind supports social login via [WorkOS AuthKit](https://workos.com/), allowing users to sign in with Google, Microsoft, or GitHub. To enable it, you need a WorkOS account and the following three environment variables: * `WORKOS_API_KEY` - Your WorkOS API key * `WORKOS_CLIENT_ID` - Your WorkOS application Client ID * `WORKOS_REDIRECT_URI` - The callback URL for OAuth redirects (e.g., `https://your-packmind-instance.com/api/v0/auth/social/callback`) If you use Docker Compose, add these variables to the `api` section of your `docker-compose.yml`: ```yaml theme={null} api: environment: WORKOS_API_KEY: WORKOS_CLIENT_ID: WORKOS_REDIRECT_URI: https://your-packmind-instance.com/api/v0/auth/social/callback ``` Then restart with: ```bash theme={null} docker compose up -d ``` Once configured, social login buttons (Google, Microsoft, GitHub) will appear on the sign-in page. Social login is a convenience feature that provides additional sign-in methods alongside email/password. It is not a full SSO solution: you cannot restrict users to a specific social login provider or disable email/password authentication in favor of social login only. ## Configure deployment and environment variables ### Override environment variables #### With Docker Compose You can override the `api` section of the `docker-compose.yaml` file. Here is an example of how to add the `SMTP_FROM` variable to Docker Compose. ```yaml theme={null} api: image: packmind/api:${PACKMIND_TAG:-latest} container_name: packmind-api ports: - '3000:3000' environment: <<: [*database-url, *redis-config, *openai-config] SMTP_FROM: username@acme.org ``` #### With Helm Chart Follow the instructions on the [Helm Chart GitHub repository](https://github.com/PackmindHub/packmind-ai-helm-chart) on how the YAML values file. ### List of Environment variables Database Configuration: * `DATABASE_URL`️ - PostgreSQL database connection URL used by the API, TypeORM migrations, and data sources Application URLs & CORS: * `APP_WEB_URL` - Base URL of the web application, used for generating links in password reset and invitation emails * `CORS_ORIGINS` - Comma-separated list of allowed origins for CORS (Cross-Origin Resource Sharing) configuration Redis Configuration: * `REDIS_URI` - Full Redis connection URI used for caching and SSE (Server-Sent Events) client connections ### SMTP Configuration * `SMTP_HOST` - SMTP server hostname for sending emails * `SMTP_PORT` - SMTP server port number * `SMTP_SECURE` - Whether to use secure connection (TLS/SSL) for SMTP * `SMTP_USER` - Username for SMTP authentication * `SMTP_PASSWORD` - Password for SMTP authentication * `SMTP_FROM` - Default sender email address for outgoing emails * `SMTP_IS_EXCHANGE_SERVER` - Flag indicating if the SMTP server is a Microsoft Exchange server * `SMTP_TLS_REJECT_UNAUTHORIZED` - Whether the SMTP server's TLS certificate must be valid and trusted. Defaults to `false`; set it to `true` to enable certificate verification. Only `true` and `false` are accepted — any other value is rejected with an error rather than treated as `false`, so a typo cannot silently leave verification off By default Packmind does **not** verify the TLS certificate of your SMTP server, which leaves outgoing mail open to man-in-the-middle interception. Set `SMTP_TLS_REJECT_UNAUTHORIZED` to `true` to turn verification on. If your SMTP server uses a self-signed certificate or a private Certificate Authority, trust that CA with `NODE_EXTRA_CA_CERTS` (see [Add custom CA certificates](#add-custom-ca-certificates-docker-compose)) so you can enable verification rather than leaving it off. Authentication & Security: * `API_JWT_SECRET_KEY` - Secret key used by the API for signing and verifying JWT tokens for authentication * `ENCRYPTION_KEY` - Key used for encrypting sensitive data like password reset tokens, invitations, and git provider credentials * `MAX_LOGIN_ATTEMPTS` - Maximum number of failed login attempts before rate limiting is triggered (defaults to a configured value if not set) * `LOGIN_BAN_TIME_SECONDS` - Duration (in seconds) for which user will not be allow to try to login again. Social Login (WorkOS): * `WORKOS_API_KEY` - API key from your WorkOS dashboard for social login authentication * `WORKOS_CLIENT_ID` - Client ID of your WorkOS application * `WORKOS_REDIRECT_URI` - OAuth callback URL, must point to your Packmind instance (e.g., `https://your-packmind-instance.com/api/v0/auth/social/callback`) API Integration: * `OPENAI_API_KEY` - API key for accessing OpenAI services for customizing standards and commands for AI Agents. Monitoring & Debugging: * `PACKMIND_LOG_LEVEL` - Log level for Packmind logger (e.g., 'debug', 'info', 'warn', 'error') ## Next Steps After setting up your self-hosted Packmind instance: 1. **[Install the CLI](./gs-cli-setup)** - Set up the Packmind CLI and authenticate with your instance 2. **[Start Onboarding](./gs-onboarding)** - Scan your codebase to create your first standards # Set Up Your Project with Onboarding Source: https://docs.packmind.com/getting-started/gs-onboarding ## Overview Packmind automatically generates coding standards and commands from your project. Instead of manually creating standards from scratch, your AI agent analyzes your existing code and practices to create a foundation you can refine. ## Skill-Based Onboarding The `/packmind-onboard` skill provides automated batch analysis of your codebase, generating both standards and commands. ### Prerequisites * Packmind CLI installed * Logged in with `packmind login` * Packmind skills installed with `packmind init` * A Git repository in your project ### Quick Start In your AI agent (Claude Code, Cursor, etc.), invoke the onboarding skill: ``` /packmind-onboard ``` The skill guides you through an interactive process: 1. **Create or select a package** — Where your standards and commands will be stored 2. **Analyze your codebase** — Read-only scan for patterns and conventions 3. **Review generated drafts** — Preview before creating anything 4. **Create standards and commands** — Publish to Packmind and deploy locally ### What Gets Generated Based on your project's patterns, you'll get up to: **Standards** (max 5 per run) * Role taxonomy drift patterns * Test data construction patterns **Commands** (max 5 per run) * File template workflows * CI/local development parity scripts All items are created as **drafts first**, giving you a chance to review and edit before publishing. ### The Onboarding Flow #### Step 1: Package Selection The skill checks for existing packages: * **No packages exist**: Automatically creates `{repo-name}-standards` * **One package exists**: Asks if you want to use it or create a new one * **Multiple packages**: Lists all options for you to choose #### Step 2: Codebase Analysis The skill performs a read-only scan of your project, detecting your tech stack, frameworks, and coding patterns. #### Step 3: Draft Review After analysis, you see a summary of what will be created (e.g., "3 standards, 2 commands"). You can then choose: * **Create all now** — Publish everything to Packmind * **Let me review drafts first** — Edit the drafts before publishing * **Cancel** — Exit without creating anything #### Step 4: Publishing When you confirm, the skill publishes everything to Packmind and deploys to your local AI agent automatically. ### After Skill-Based Onboarding Once complete, your standards and commands are: * **Published to Packmind** — Available in your organization * **Added to your package** — Ready for team distribution * **Deployed locally** — Active in your AI agent (Claude Code, Cursor, GitHub Copilot, etc.) ### Re-running Skill-Based Onboarding Run the skill again anytime to generate additional standards and commands. The skill never overwrites existing items. *** ## Troubleshooting **Q: Skill says I'm not logged in** Run `packmind login` first, then retry the skill. **Q: Package creation fails** Check your network connection and that you have permissions to create packages in your organization. **Q: No patterns discovered** Very new or small codebases may not have enough patterns to detect. Try running the skill again after adding more code to your project. **Q: Generated standards don't match my project** Onboarding generates a starting point. Edit draft files before confirming to customize them to your needs. ## Related Documentation * [Create and customize standards](/getting-started/gs-create-standard) * [Create and customize commands](/getting-started/gs-create-command) * [Distribute standards and commands](/getting-started/gs-distribute) * [CLI Reference](/tools/cli) # Distribute artifacts Source: https://docs.packmind.com/governance/distribution Now that Packmind contains coding standards, commands, and skills, let's distribute them to your Git Repositories. The distribution will commit instructions files that will be used by AI Agents (Claude Code, Cursor, etc.). ## Supported AI Agents Packmind supports multiple AI coding assistants. Organization administrators can choose which agents to enable in **Settings** → **Distribution** → **Rendering**. See [Manage AI Agent Rendering](/administration/manage-ai-agents) for details. For a detailed breakdown of where standards, commands, and skills appear for each AI assistant, see [Understanding Where Your Artifacts Appear](/concepts/artifact-rendering). **Default skills included** — All distributions automatically include Packmind's default skills (such as `packmind-update-playbook` for creating and updating playbook artifacts with AI assistance). These are added alongside your package contents regardless of which distribution method you use. **Need support for a new AI agent?** You can create an issue in our [repository](https://github.com/PackmindHub/packmind) to request support for additional AI coding assistants. ## How to Distribute There are two ways to distribute packages to your repositories: 1. **Using the Packmind app** - Distribute packages through the web interface with full control over targets and repositories 2. **Using the Packmind CLI** - Install packages directly from your terminal, useful for CI/CD pipelines and local development ### Distribution Methods Overview | Method | Best For | Git Provider Management | | - | - | - | | **App** | Centralized distribution, team coordination | Full control via connected Git providers | | **CLI** | CI/CD pipelines, local development | Creates read-only provider entries | ## Distribute via the App To distribute standards, commands, and skills, you need to add them to a package. A package is a curated collection of commands, standards, and skills grouped together (e.g., "Frontend React Standards", "Backend API Guidelines"). When you distribute a package: * All commands, standards, and skills in the package are distributed together * The latest version of each item is used * A single commit contains all the package content * You can distribute multiple packages at once to the same target To distribute packages: 1. Navigate to the **Packages** section 2. Select the package(s) you want to distribute 3. Click **Distribute** and choose your target repositories 4. Confirm the Distribution This approach is useful when you want to: * Distribute related guidelines together * Maintain consistent sets of standards across projects * Organize guidelines by technology, team, or project structure For more information on creating and managing packages, see [Packages Management](/concepts/packages-management). ## Distribute via the Packmind CLI You can also distribute packages directly from your terminal using the `packmind` command: ```bash theme={null} packmind install ``` For example: ```bash theme={null} packmind install backend-standards frontend-react # Note: when using multiple spaces, you will need to prefix the packages with the space slug packmind install @backend/standards @frontend/react ``` When your organization uses multiple [Spaces](/concepts/spaces), prefix package slugs with the space slug using `@space/package` notation. This will: 1. Fetch the specified packages from Packmind 2. Generate the instruction files for all enabled AI agents 3. Write the files to your local repository 4. Notify Packmind that a distribution occurred ### CLI Distribution Considerations When you distribute packages using the CLI, Packmind automatically creates a Git provider entry to track the distribution. However, these CLI-created providers have some limitations: **Limited Provider Management** — Git providers created through CLI distributions are not authenticated. This means you cannot trigger new distributions from the app for these repositories, you cannot add new targets to these providers from the app, and the provider appears in your organization's Git settings but with limited functionality. To enable full management from the app, connect a Git provider in **Settings** → **Git Providers** — using the [GitHub App](/governance/git-repository-connection#github-app-recommended) (recommended) or a personal access token. See [Git Repository Connection](/governance/git-repository-connection) for the full setup. Connecting a provider later does not lose what the CLI recorded. Once a connection exists for the same host — github.com, gitlab.com or your self-managed instance — the CLI records new repositories under it, and adding a repository the CLI already recorded moves it there with its targets and distribution history. The CLI-created entry disappears from your Git settings once it holds no repository. ### When to Use CLI Distribution The CLI approach is ideal for: * **CI/CD pipelines** - Automate distribution as part of your deployment process * **Local development** - Quickly install packages without leaving your terminal * **Monorepos** - Use `packmind install` to install packages for all `packmind.json` files in the repository * **Repositories without a connection** - Distribute to repositories that aren't connected to the app ## Distribution History and the Tracked Branch Every package, standard, command, and skill has a **Distribution History** listing when it was distributed and where it landed. When your organization tracks a repository and branch (see [Git Track](/tools/cli#git-track)), Packmind shows the **branch you currently track**. Distributions made on other branches of the same repository are hidden, so the view stays focused on the branch your team works from today. This applies to both places branches surface: * **Distribution History** — entries recorded on another branch of a tracked repository are not listed. * **The Deployments overview** — the repositories list only shows the tracked branch, so a repository never appears twice under two branches. Repositories you have never tracked are unaffected — every branch keeps showing in both views. ### When the Tracked Branch Is Deleted A branch usually disappears the day its pull request is merged. Tracking survives it, and since distributions are only recorded on the tracked branch, nothing is recorded from then on — with no error anywhere to say so. Packmind checks the tracked branch against your Git provider and flags it when it is gone: * **Settings → Targets** — the repository card carries a **Branch deleted** marker. * **The Git connection panel** — the tracked branch is marked in the repositories list, where an admin manages tracking. * **`packmind git info`** — reports that the branch is not in the repository and offers to move tracking. **Needs a Git connection** — checking a branch means asking your Git provider, so the two web app markers only appear for repositories reached through a connection. A repository Packmind knows only from `packmind install` carries no credentials to ask with, and `packmind git info` is the signal there. To start recording again, an organization admin moves tracking to a branch that exists: ```bash theme={null} packmind git track --update --branch main ``` Nothing recorded on the deleted branch is lost — its history is kept, exactly as when tracking moves for any other reason. ### Moving the Tracked Branch Is Reversible Moving tracking to another branch never deletes anything: * Distributions recorded on the branch you leave are **kept**, just no longer displayed. * Move tracking back and the earlier history reappears, with new distributions added to it. So a team that tracks `main`, moves to `dev` for a while, then returns to `main` finds their original `main` history intact and continuing where it left off. **Only one branch at a time** — Packmind shows the tracked branch's history rather than several branches side by side. To see another branch's history, ask an organization admin to move tracking to it, either with **change branch** in the Git connection panel (see [Changing a Repository's Branch](/governance/git-repository-connection#changing-a-repositorys-branch)) or with `packmind git track --update`. ### Removing Tracking An organization admin can take a repository out of the governance views entirely by running `packmind git untrack` from a clone of it (see [Git Untrack](/tools/cli#git-untrack)). The repository disappears from Distribution History and the Deployments overview. Nothing is deleted. Every distribution recorded before the removal is kept, and tracking the same branch again brings the whole history back, with new distributions appended to it. Tracking a different branch instead starts that branch's history fresh, while the original branch's history stays retained and returns whenever you track it again. While a repository is untracked, `packmind install` behaves exactly as it does for a repository that was never tracked: it completes locally and tells you the distribution was not recorded. ## Keep the Distribution State in Sync with Your Repository What a target runs is whatever its `packmind-lock.json` says. Each lock lists the version of every package distributed to that folder: ```json theme={null} { "packages": { "@my-space/ops": "1.2.3" } } ``` Both `packmind install` and distributions from the app write this file, and removing a package from a target in the app removes it from the lock too. ### When Packmind Reads the Lock Files Packmind refreshes the distribution state from the lock files on the tracked branch on its own when: * **A repository is tracked** — the lock files already in the repository are read when it is connected. * **The tracked branch changes** — the new branch's lock files are read. Distributions of the previous branch are kept as history but no longer shown. * **A target is added** — the lock at the target's path is read. If there is none, the target shows no distribution. * **A target's path is renamed** — the lock at the new path is read. Earlier distributions stay with the target. ### Sync from the App When a lock file changed outside Packmind — for example someone edited it by hand — refresh the state yourself: 1. Open the **Distribution** page and select the repository. 2. In the repository's detail pane, click **Sync from repository**. Packmind reads every `packmind-lock.json` on the tracked branch and updates the targets that changed: * A lock in a folder no target declares creates that target. * A package missing from a lock is kept while the `packmind.json` next to it still lists it; otherwise it is recorded as removed. * A lock that already matches what Packmind shows records nothing. If some lock files could not be used, a **Some lock files weren't fully recorded** banner lists them, grouped by target: * **A package unknown to your organization** — that package is not recorded. * **A lock written by an older CLI** — the lock records no package versions, so it is ignored. Distribute to that target again to refresh it. **Needs a working Git connection** — Syncing reads the repository through your Git provider. When the connection is missing or broken (for example an expired token), **Sync from repository** is disabled and its tooltip asks you to fix the Git connection first. See [Git Repository Connection](/governance/git-repository-connection). ### Record from Your Terminal You can also send your local lock files to Packmind with the CLI. From the tracked branch, run: ```bash theme={null} packmind distribution record ``` Run from the repository root, it records every target; run from a sub-folder, only the targets at or below it. It finds the lock files through Git, so folders your `.gitignore` excludes are skipped. It works even when your lock edits are not pushed yet — but the next **Sync from repository** reads the locks on the remote branch and shows that state again, so push your changes. See [Distribution Record](/tools/cli#distribution-record). ## Removing Packages When you no longer need a package in your repository, you can remove it using either the app or the CLI. ### Remove via the App In the Packmind app, you can remove packages one-by-one from your distributions: 1. Navigate to the **Packages** section 2. Open the package you want to remove 3. Click **Remove from target** and confirm the removal ### Remove via the CLI There are two ways to remove packages using the CLI: **Option 1: Use the remove command** ```bash theme={null} packmind uninstall ``` For example: ```bash theme={null} packmind uninstall backend-standards ``` **Option 2: Edit packmind.json and reinstall** 1. Open your `packmind.json` file 2. Remove the package slug from the packages list 3. Run the install command to update your repository: ```bash theme={null} packmind install ``` This approach is useful when you want to make multiple changes to your package configuration at once. ## Publishing to a Marketplace Besides committing instruction files into your repositories, you can publish a package as a **managed plugin** to a marketplace so your team can install it directly in Claude Code or GitHub Copilot. See [Publish to a marketplace](/governance/marketplaces) for how to link a marketplace, publish packages, and monitor adoption. ## Retiring a Published Plugin If a package was published to a marketplace as a managed plugin, you can retire it through a dedicated flow that opens a deletion pull request in the marketplace repository. See [Retire a plugin from a marketplace](/governance/retire-plugin) for the step-by-step process. # Git Repository Connection Source: https://docs.packmind.com/governance/git-repository-connection Only users with **Admin** privileges can configure Git providers and manage repositories. If you need to connect repositories, contact your organization administrator. Packmind connects to your GitHub and GitLab repositories so it can distribute your standards, commands, and skills. Before you can distribute, an administrator connects at least one Git provider from **Settings** → **Git Providers**. ## Supported Git Providers Packmind supports **GitHub** and **GitLab**. You add and manage connections from **Settings** → **Git Providers**, on the **Connections** tab. Click **Add connection** to open the connection panel. For GitHub, you can authenticate with the **GitHub App** (recommended) or a **personal access token**. GitLab connections use a personal access token. ## Connecting GitHub ### GitHub App (recommended) The GitHub App is the recommended way to connect GitHub repositories: * **Scoped access** — you choose exactly which organizations and repositories Packmind can reach. Nothing else is visible to Packmind. * **Automatic credential rotation** — Packmind refreshes its access on its own, so there's no token to create, store, or renew. How you connect depends on whether you use Packmind Cloud or a self-hosted instance. #### On Packmind Cloud 1. Go to **Settings** → **Git** and click **Add connection**. 2. Select **GitHub** as the vendor. 3. (Optional) Enter a **display name** to identify this connection later. 4. Under **Authentication**, click **Install Packmind on GitHub**. 5. On GitHub, choose the organizations and repositories you want to grant access to, then confirm. 6. You're returned to Packmind automatically, and the connection is ready to use. #### On self-hosted Packmind The first time you connect, you register a Packmind GitHub App. This is a one-time setup — every later GitHub connection reuses it. 1. Go to **Settings** → **Git** and click **Add connection**. 2. Select **GitHub**. 3. (Optional) Under **Authentication**, enter a **GitHub organization** slug (the name that appears in `github.com/`) to register the app under that organization — you must be one of its owners. Leave the field empty to register the app under your personal GitHub account. 4. Click **Register the Packmind GitHub App**. GitHub opens so you can create the app, then returns you to Packmind automatically. 5. Once the app is registered, click **Install Packmind on GitHub**. 6. On GitHub, choose the organizations and repositories to grant access to, then confirm. 7. You're returned to Packmind automatically, and the connection is ready to use. For team use, prefer registering the app under a GitHub organization so it isn't tied to one person's account. If you already registered it under a personal account, you can move it afterward on GitHub: open the app's settings, go to **Advanced**, and use **Transfer ownership** to hand it to your organization. After the app is registered, every new GitHub connection in your organization reuses it — you only register once. To remove the registration, use **Revoke registration**. This is only available once no connections are still using the app, so delete those connections from the **Connections** tab first. ### Personal access token If you can't use the GitHub App, you can connect with a personal access token instead. In the **Add connection** panel, choose **Use a personal access token instead**, then: 1. Go to **GitHub Settings** → **Developer settings** → **Personal access tokens**. 2. Click **Generate new token** (classic). 3. Permissions must include **Contents: read/write** (or the `repo` scope for classic tokens). 4. Copy your token (it starts with `ghp_` or `github_pat_`) and paste it into Packmind. Personal access tokens don't rotate automatically — you'll need to renew them before they expire. Prefer the GitHub App when you can. ## Connecting GitLab GitLab connections use a personal access token: 1. Go to **GitLab User Settings** → **Access Tokens**. 2. Create a new token with the `api` scope (full API access). 3. Copy your token (it starts with `glpat-`) and paste it into Packmind. For a self-managed GitLab, enter your instance URL (for example `https://gitlab.acme.io`). Packmind matches repositories to the connection by host, so a clone over HTTPS or SSH reaches the same connection. ## Managing Repository Access To change which repositories a GitHub App connection can reach, open the connection from the **Connections** tab and use **View Packmind on GitHub**. This opens the Packmind app's page on GitHub, where you can add or remove repositories. The new access takes effect in Packmind without reconnecting. ## Adding Repositories Once you've added your providers, **add repositories** for each provider. When you add a Git repository, Packmind automatically creates a default target with the root path "/" for that repository. This allows you to immediately start distributing standards and commands to the entire repository. You can later create additional targets for specific paths within the repository if needed. A repository the CLI already distributed to keeps its history when you add it: it moves under the connection with its existing targets instead of being created again, and the CLI-created entry for that host disappears once it holds no repository. A repository you add from the Git connection panel is tracked on its default branch. ## Changing a Repository's Branch Each repository is distributed to and tracked on one branch. To move it to another branch: 1. Open the connection from the **Connections** tab and click **Manage**. 2. Next to the repository, click **change branch** and type the branch name, then press Enter. 3. Click **Apply changes**. The new branch replaces the current one rather than being added next to it. Packmind checks the branch with your Git provider first: a branch that doesn't exist is refused with an error under the field, and if the provider can't be reached nothing changes and you are asked to try again. Changing the branch never deletes history. Distributions recorded on the branch you leave are kept, and switching back shows that branch's history again — see [Moving the Tracked Branch Is Reversible](/governance/distribution#moving-the-tracked-branch-is-reversible). A repository added before branches were tracked may still list several branches. The first time you change its branch, Packmind starts tracking the one you chose and shows only that branch from then on. ## Distribution Targets Before distributing your standards and commands, you can configure targets in **Settings** → **Distribution** → **Targets**. A target defines a specific path within your Git repository where standards and commands will be distributed. Targets are particularly useful in monorepo environments where you want to apply different standards to different parts of your codebase. For example: * `/frontend/` - Apply frontend-specific standards to your React components * `/apps/api/` - Distribute backend standards to your API code * `/packages/shared/` - Apply shared library standards to common utilities * `/` (Created by default when you add a Git Repo) Each target creates instruction files in its specified path, allowing AI agents to follow the appropriate standards based on the code they're working with. # Install a plugin from a marketplace Source: https://docs.packmind.com/governance/install-plugin Once a plugin shows **Published** in Packmind, here is how to install it and check it works. ## GitHub Copilot CLI Add the marketplace, once: ```bash theme={null} copilot plugin marketplace add https://github.com// ``` List what it offers. The marketplace name comes from its descriptor, not the repository: ```bash theme={null} copilot plugin marketplace browse ``` Install: ```bash theme={null} copilot plugin install @ ``` **Restart Copilot.** A session already running won't pick up the plugin, and your install is only reported to Packmind at session start. In the new session, call one of the plugin's skills to confirm: ``` /: ``` ## After a republish Copilot caches the catalogue, so refresh it first — otherwise you keep getting the previous version with nothing saying so. From inside a Copilot session: ``` /plugin marketplace refresh ``` Or from a shell, naming the marketplace (omit the name to refresh them all): ```bash theme={null} copilot plugin marketplace update ``` A session that is already open does not see a catalogue refreshed from a shell. Refresh from inside the session, or quit it first. Then update the plugin and restart Copilot: ```bash theme={null} copilot plugin update ``` ## Claude Code Same sequence from inside a session: `/plugin marketplace add /`, install from the `/plugin` menu, restart, then call a skill. Your install appears in the plugin's **Adoption** tab after your first session with it enabled — not at install time. ## Related Documentation * [Publish to a marketplace](/governance/marketplaces) — link a marketplace and publish packages as plugins # Publish to a marketplace Source: https://docs.packmind.com/governance/marketplaces A marketplace lets you distribute Packmind packages as **managed plugins** through a Git repository, so your team can install them directly in Claude Code or GitHub Copilot. Instead of committing instruction files into each project, you publish a package once and Packmind keeps the marketplace repository up to date for you. ## Overview A marketplace is a Git repository that hosts a marketplace descriptor — the catalogue your coding assistant reads to discover and install plugins. A marketplace targets either **Claude Code** or **GitHub Copilot**, never both — Packmind picks up which one automatically from the descriptor file the repository contains, so you don't choose it yourself when linking. When you publish a package to a marketplace, Packmind: * Renders the package's skills and commands into a plugin for that marketplace's assistant. * Opens (or amends) a single **Packmind sync** pull request on the marketplace repository. * Adds the plugin to the marketplace catalogue once you merge that pull request. With a marketplace in place you can: * **Publish** a package as a plugin your whole organization can install. * **Track** every publish attempt and its status. * **Monitor** the marketplace's health and who has adopted each plugin. * **Retire** plugins that are no longer needed. A marketplace targets **Claude Code** or **GitHub Copilot** depending on which descriptor file its repository contains: `.claude-plugin/marketplace.json` (or `marketplace.json` at the repository root) makes it a Claude Code marketplace, while `.github/plugin/marketplace.json` makes it a GitHub Copilot marketplace. A repository can only expose one of the two. To distribute standards, commands, and skills as instruction files across other AI assistants (Cursor and more), use the standard [distribution flow](/governance/distribution) instead. ## Before you start * **Connect a Git provider.** The marketplace repository must be reachable through a connected Git provider — the [GitHub App](/governance/git-repository-connection#github-app-recommended) (recommended) or a personal access token. Providers created automatically by the CLI can't be used, because they hold no credentials. See [Git Repository Connection](/governance/git-repository-connection). * **Prepare the marketplace repository.** It must contain a marketplace descriptor: `.claude-plugin/marketplace.json` (or `marketplace.json` at the root) to target Claude Code, or `.github/plugin/marketplace.json` to target GitHub Copilot. Whichever one Packmind finds decides the marketplace's type. * **Be an organization administrator.** Only admins can link or unlink a marketplace. Any organization member can publish packages to a linked marketplace. ## Link a marketplace Only organization administrators can link a marketplace. 1. Navigate to **Marketplaces** in your organization. 2. Click **Link a marketplace**. 3. Choose a **Git connection** from your connected providers. 4. Pick the **repository** that hosts the marketplace. Use the search box to filter a long list. 5. Click **Link marketplace**. Packmind validates that the repository exposes a valid marketplace descriptor, and determines whether the marketplace targets Claude Code or GitHub Copilot from which descriptor file it finds. Once linked, the marketplace appears in the list with its contents and health at a glance. If you don't have a Git provider connected yet, the form guides you to **Settings** → **Git Providers** to set one up first. ## Publish a package as a plugin You publish from the same **Distribute** menu you use for repositories. 1. Navigate to the **Packages** section. 2. Select the package (or packages) you want to publish. 3. Click **Distribute** and choose **To marketplaces**. 4. In the **Publish to a marketplace** dialog, pick the target marketplace. 5. Click **Publish**. Packmind opens or amends the **Packmind sync** pull request on the marketplace repository. Review that pull request and **merge it** to make the plugin live. Once it is live, your team installs it from their assistant — see [Install a plugin from a marketplace](/governance/install-plugin). **Packages need a skill or a command.** A marketplace plugin must contain at least one skill or command. Packages that contain only standards can't be published as plugins. ## Track distributions Open a marketplace to see its plugins and every publish attempt. Each publish creates a distribution record you can follow through its lifecycle: | Status | Meaning | | - | - | | **In progress** | Packmind is preparing the plugin files. | | **Pending PR review** | The Packmind sync pull request is open and waiting to be merged. | | **Published** | The pull request was merged and the plugin is live in the marketplace. | | **Removal pending** | You requested removal; the deletion is being prepared. | | **To be removed** | The deletion pull request is open, waiting to be merged. | | **Removed** | The plugin has been removed from the marketplace. | | **Failed** | The publish couldn't complete. See the reason on the row and try again. | Packmind checks the marketplace periodically and moves a distribution from **Pending PR review** to **Published** as soon as it confirms the pull request was merged. If you'd rather not wait, use **Sync now** to check immediately. ## Monitor marketplace health Each marketplace shows a health indicator so you can spot problems early: | State | Meaning | | - | - | | **Healthy** | The marketplace matches what Packmind expects. | | **Drift** | A plugin Packmind considers published is missing, or the catalogue changed outside Packmind. Review the listed plugin slugs. | | **Unreachable** | Packmind couldn't reach the repository — for example an authentication or network error. | | **Bad format** | Packmind reached the repository but `marketplace.json` is missing or can't be read. An admin needs to fix the descriptor. | When drift is detected, either mark the affected plugin for removal (if the change was intentional) or restore it in the marketplace repository (if it was a mistake). See [Retire a plugin from a marketplace](/governance/retire-plugin#drift-detection) for the full workflow. ## Monitor adoption Open a plugin and switch to the **Adoption** tab to see who is using it. You can view adoption two ways: * **By repo** — which repositories have installed the plugin. * **By person** — which people have installed it. Each entry shows whether it's **Up to date** or **Outdated** compared with the published version, so you can tell when consumers are running an older build and nudge them to update. Adoption data appears after someone starts a session with the plugin enabled, in Claude Code or GitHub Copilot. A newly published plugin shows no consumers until it's installed and used — see [Install a plugin from a marketplace](/governance/install-plugin) for what your team has to do. ## Retire a plugin When a plugin is no longer needed, retire it through the guided, pull-request-governed flow — the same rolling **Packmind sync** pull request used to publish. See [Retire a plugin from a marketplace](/governance/retire-plugin) for the complete process, including cancelling a pending removal and handling drift. ## Unlink a marketplace Only organization administrators can unlink a marketplace. 1. Navigate to **Marketplaces**. 2. Find the marketplace in the list. 3. Use its row action to **Unlink** and confirm. Unlinking stops Packmind from tracking the repository. It does not delete plugins already published to the marketplace — those remain in the repository until you remove them. ## Troubleshooting * **Problem**: The **To marketplaces** option is greyed out. * **Solution**: Your selection contains only standards. Add at least one skill or command to the package, or select a package that already has one. * **Problem**: Linking fails with a descriptor error. * **Solution**: Confirm the repository has a valid marketplace descriptor — `.claude-plugin/marketplace.json` (or `marketplace.json`) for Claude Code, or `.github/plugin/marketplace.json` for GitHub Copilot — and that the connected Git provider can access it. * **Problem**: A publish stays at **Pending PR review**. * **Solution**: The Packmind sync pull request hasn't been merged yet. Open it on the marketplace repository, review, and merge. Use **Sync now** to refresh the status afterwards. * **Problem**: The marketplace shows **Unreachable**. * **Solution**: Check that the Git provider is still connected and authorized, then use **Sync now** to retry. * **Problem**: A publish fails with a name conflict. * **Solution**: A plugin with the same name already exists in the marketplace and isn't managed by Packmind. Rename or remove the conflicting entry, then publish again. * **Problem**: A publish fails saying the marketplace's type changed. * **Solution**: The repository's descriptor file was swapped for the other assistant's after the marketplace was linked — for example `.claude-plugin/marketplace.json` was replaced with `.github/plugin/marketplace.json`, or the other way around. Packmind doesn't pick up a type change on its own, to avoid silently rewriting the marketplace in a different format. Restore the original descriptor, or unlink and relink the marketplace to adopt its new type. ## Related Documentation * [Install a plugin from a marketplace](/governance/install-plugin) — what your team does to install a published plugin * [Distribute artifacts](/governance/distribution) — distribute packages to Git repositories and via the CLI * [Retire a plugin from a marketplace](/governance/retire-plugin) — remove a published plugin through the governed flow * [Git repository connection](/governance/git-repository-connection) — connect the marketplace repository to Packmind * [Packages Management](/concepts/packages-management) — group standards, commands, and skills into packages # Distribution Overview Source: https://docs.packmind.com/governance/overview The Distribution Overview provides a centralized view of where your commands, standards, and skills are distributed across your organization's Git repositories and targets. ## What You Can Do ### View Distributions from Multiple Perspectives Switch between three tabs to analyze your distributions: * **By packages** - See your distributions grouped by package * **By repository** - See all commands, standards, and skills distributed to each Git repository and target * **By marketplace** - See your distributions grouped by marketplace ### Track Version Status Quickly identify outdated distributions: * **Up-to-date** - Distributed version matches the latest version * **Outdated** - Distributed version is older than the latest version Targets represent specific paths within repositories where artifacts are distributed (e.g., `/`, `/src/frontend/`, `/src/backend/`). Each target can have different versions of commands, standards, and skills distributed. # Retire a plugin from a marketplace Source: https://docs.packmind.com/governance/retire-plugin When a published plugin becomes deprecated or no longer fits your marketplace, you can retire it through a guided, PR-governed flow. Packmind tracks the lifecycle so you and your team always know which plugins are live, which are pending removal, and which have already been removed. ## Overview Retiring a plugin mirrors how you published it: 1. You mark the plugin for removal from the Packmind app. 2. Packmind automatically opens (or amends) the deletion pull request in the marketplace repository on your behalf — the same governed flow used to publish. 3. You review and merge that pull request. 4. Once the pull request is merged, Packmind confirms the removal and updates the plugin status to **Removed**. While the deletion pull request is in flight, the plugin appears as **To be removed** in the marketplace details view, so the whole team can see what's pending. ## Mark a plugin for removal 1. Navigate to **Marketplaces** in your organization. 2. Open the marketplace that hosts the plugin you want to retire. 3. In the **Distributions** list, find the row for the plugin. 4. Click the **Remove** action on that row. 5. Confirm the removal in the dialog. The plugin status changes to **To be removed**, and Packmind immediately opens the deletion pull request on the marketplace repository. Only organization administrators can mark a plugin for removal. ## Review and merge the deletion pull request Marking a plugin for removal automatically opens (or amends) the **Packmind sync** pull request on the marketplace repository — the same rolling pull request Packmind uses to publish. The pull request removes the plugin's entry from the marketplace descriptor and deletes its rendered files. You don't need to run any CLI command. To finish the retirement: 1. Open the **Packmind sync** pull request in the marketplace repository. 2. Review the removal alongside any other pending Packmind changes. 3. Merge the pull request against the marketplace's default branch. Once the pull request is merged, the next marketplace reconciliation run detects that the plugin is gone from the marketplace descriptor and transitions the distribution to **Removed**. ## Retire a plugin when deleting its Packmind package When you delete a Packmind package that is already published to one or more marketplaces, Packmind automatically marks every live distribution of that package as **To be removed** across all affected marketplaces and opens the deletion pull request on each one. You don't need to visit each marketplace one by one. You still need to finish each retirement by reviewing and merging the deletion pull request in every affected marketplace, as described above. ## Drift detection Packmind regularly checks each marketplace against what it expects to find there. If a plugin that Packmind considers **Published** disappears from a marketplace without going through the retirement flow above, the marketplace details view surfaces a **Drift detected** indicator listing the affected plugin slugs. Drift usually means someone deleted a plugin directly in the marketplace repository, bypassing Packmind. To resolve it: * If the deletion was intentional, mark the plugin for removal in Packmind to align the lifecycle. * If the deletion was a mistake, restore the plugin in the marketplace repository. A plugin that is currently in **To be removed** state never triggers drift — Packmind knows the deletion is expected and waits for the deletion pull request to be merged. ## Plugin statuses at a glance | Status | Meaning | | - | - | | **Published** | The plugin is live in the marketplace and ready for consumers. | | **To be removed** | You've requested removal; the deletion pull request is expected. | | **Removed** | The plugin has been removed from the marketplace and reconciliation confirmed it. | ## Related Documentation * [Publish to a marketplace](/governance/marketplaces) — link a marketplace, publish packages as plugins, and monitor adoption * [Distribute artifacts](/governance/distribution) — publish packages to repositories and marketplaces * [Git repository connection](/governance/git-repository-connection) — connect the marketplace repository to Packmind * [Packmind CLI](/tools/cli) — reference for the `packmind plugins delete` command, which removes a rendered plugin from a local workspace clone # Introduction Source: https://docs.packmind.com/index ## What's Packmind Packmind is a developer tool that fixes two big problems every AI-native engineer runs into: ### **1️⃣ “What do I even put in these AI instructions?”** Every tool expects its own inputs: * **Copilot** → `.github/copilot-instructions.md`, chat modes, reusable prompts * **Claude** → `CLAUDE.md`, commands, skills * **Cursor** → `.cursor/rules/*.mdc` * *(with more formats appearing every month…)* But your team’s **actual standards aren’t stored anywhere**: * architecture rules → buried in Slack or Notion * naming conventions → stuck in your head * patterns → hiding in PR comments * best practices → scattered across repos 👉 **Packmind helps you turn all of this into a real engineering playbook** (standards, commands, skills) so **AI agents finally code *your way*.** *** ### **2️⃣ “Why am I copy-pasting this across every repo and every agent?”** Every repo. Every assistant. Different files, different folders, different formats. Keeping everything in sync is impossible. 👉 **Packmind centralizes your playbook once — and distributes it everywhere**, generating the exact instruction files each AI tool needs, optimized for context. *** ## Getting Started ### Quick Start 1. **[Create your Packmind account](./getting-started/gs-install-cloud)** or **[set up self-hosted](./getting-started/gs-install-self-hosted)** 2. **[Install the CLI](./getting-started/gs-cli-setup)** and authenticate 3. Run `/packmind-onboard` in your AI coding assistant The `/packmind-onboard` command will guide your AI agent to automatically analyze your codebase and create standards and commands based on the patterns it discovers. ### What Happens During Onboarding When you run `/packmind-onboard`, the AI agent will: * 📁 **Scan your repository** — Detect tech stack, frameworks, and coding patterns * 📝 **Generate standards** — Create up to 5 coding standards from your conventions * ⚡ **Create commands** — Build up to 5 reusable commands from common workflows * 📦 **Package everything** — Organize artifacts for easy distribution All generated items are created as drafts first, giving you a chance to review before publishing. ### Create Individual Artifacts You can also create standards, commands, and skills individually using the skill `packmind-update-playbook`. This skill guides your AI agent through a structured creation process. [Learn more about onboarding →](./getting-started/gs-onboarding) # Linter: Automated Detection of Coding Rules Source: https://docs.packmind.com/linter/linter **Enterprise Feature** — This functionality is only available in the **Enterprise** version of Packmind. **LLM Connection Required** — The linter feature requires an LLM (Large Language Model) connection to generate detection programs. This is **enabled by default** on Packmind Cloud. For self-hosted installations, you need to configure an LLM provider. Packmind supports five providers: **OpenAI**, **Anthropic Claude**, **Google Gemini**, **Azure OpenAI**, and any **OpenAI-compatible** endpoint (for local models such as Ollama or LM Studio). See [Install Packmind on your server](/getting-started/gs-install-self-hosted#connect-your-llm-optional-but-important) for configuration instructions. ## Overview Packmind's linter automatically detects violations of your team's coding rules in your codebase. Instead of manually reviewing code for compliance, Packmind uses AI to generate **deterministic** detection programs that identify when your rules are not being followed. For each coding rule you define, Packmind can create language-specific detection programs. These programs analyze your code and report violations, helping your team maintain consistent code quality. ## How Detection Works When you create a rule in Packmind, the system can automatically detect violations through a multi-step process: ### Step 1: Add Code Examples to Your Rule Before Packmind can detect violations, you need to provide code examples for each programming language you want to support. Code examples show the AI what compliant and non-compliant code looks like. **Requirements:** * Each language must have at least one **negative example** (code that violates the rule) * We recommend adding multiple positive examples (compliant code) and negative examples (violations) * More examples improve the quality and accuracy of detection To add code examples to a rule, see the [Standards Management](/concepts/standards-management) documentation. ### Step 2: Assessment - Can This Rule Be Detected? Once you've added code examples, Packmind **automatically triggers** an assessment to determine whether automated detection is possible for your rule. **Automatic Assessment** — Assessment is triggered automatically whenever you update code examples or Detection Clues. There is no manual trigger for assessment - the system re-evaluates detectability each time relevant inputs change (and no program generated successfully) The AI analyzes: * The rule's description * The code examples you provided * Detection Clues (tips and instructions that help AI understand how to detect violations) **Assessment Results:** **Positive Assessment**: The rule contains enough detail to create an automated detector. Packmind will proceed to generate a detection program. **Negative Assessment**: The rule is too vague or complex for automated detection. Packmind explains why detection isn't possible. Common reasons include: * The rule is subjective or depends on team context * The rule requires analyzing multiple files (not supported yet by the current linter capabilities) * The rule lacks specific, measurable criteria ### Improving Detectability When assessment fails, the **Detectability** section becomes available in the rule's detection settings. This section helps you understand and improve why detection isn't possible: 1. **View failure reasons**: See exactly why Packmind determined the rule cannot be automatically detected 2. **Answer clarification questions**: Packmind AI may generate questions to better understand your rule's context. Answering these questions helps refine the assessment 3. **Add Detection clues manually**: Provide your own tips and instructions to guide the AI in understanding how to detect violations Every update to Detection Clues triggers a new detectability assessment: * If assessment succeeds, program generation starts automatically * If assessment fails again, the explanations are updated with new insights Detection Clues remain accessible at any time once an assessment has completed (whether successful or not). You can continue to refine clues if program generation fails or produces errors. ### Step 3: Program Generation When assessment is positive, Packmind uses AI to generate a detection program for your rule. **What happens during generation:** * AI creates JavaScript source code that analyzes your code files * The program examines code structure to identify violations * Multiple generation attempts occur if initial versions don't pass validation * Generated programs are tested against your code examples to ensure accuracy **Program Testing:** * Negative examples must be flagged as violations * Positive examples must not be flagged as violations * If tests fail, Packmind refines the program and tries again ### Step 4: Draft Version Created When program generation succeeds, Packmind creates a new **draft version** of the detection program. Draft versions are not automatically used for detection. This gives you the opportunity to validate the program before it becomes active. You can test the program behavior against source code using the sandbox module in the interface, or using the [CLI](/tools/cli#lint-command). ## Understanding Program Versions Packmind manages detection programs using a versioning system: ### Draft vs Active Programs **Draft Program**: A newly generated or updated detection program that hasn't been validated yet. Draft programs can be tested but are not used for actual code analysis. It's a measure to avoid deploying versions of programs that could affect the analysis in your CI/CD pipelines for instance. **Active Program**: The validated program currently used to detect violations in your codebase. Only one program can be active per rule and language combination. ### Multiple Languages, Independent Programs Each rule can have detection programs for multiple programming languages supported by Packmind (JavaScript, TypeScript, ...) **Important**: Each language's detection program is completely independent. Generating or updating the JavaScript program doesn't affect the TypeScript program for the same rule. ### Promoting a Draft to Active To make a draft program active: 1. Test the draft program to verify it works correctly 2. Promote the draft to active status 3. The draft becomes the active program and will be used for all future code analysis Only programs with a "READY" status can be promoted to active. ## Rule Severity Each active detection program has a **severity** level that determines how violations are treated: ### Error (default) Rules with `error` severity are **blocking**. When the linter detects a violation from an error-level rule, it exits with a non-zero exit code. This makes errors ideal for **CI/CD gates** — your pipeline will fail if any error-level violations are found. ### Warning Rules with `warning` severity are **informational**. Violations are reported in the output, but they do **not** cause a non-zero exit code. Warnings won't block your pipeline — they serve as guidance for developers without enforcing a hard stop. ### Configuring Severity Severity can be configured per rule and per language from the rule's detection settings in the Packmind web interface. By default, all rules are set to `error` severity. **When to use warnings** — Warnings are useful for rules you want to gradually roll out, stylistic preferences, or best practices that shouldn't block deployments. Start with `warning` severity and promote to `error` once the team is aligned. ## Testing Draft Programs Before promoting a draft program to active, you should test it to ensure it correctly detects violations. ### Test in the Web Interface Use the **Sandbox** module in the Packmind interface to test your draft program: 1. Navigate to your rule's detection settings 2. Select the draft program you want to test 3. Enter or paste sample code in the sandbox 4. Run the detection to see if violations are correctly identified ### Test with CLI You can also test draft programs using the Packmind CLI. This allows you to run the draft program against your actual codebase before activating it. The CLI supports testing both through local `packmind.json` configuration files and through distributed standards. For complete CLI testing instructions, see the [CLI documentation](/tools/cli). ## Multi-Language Detection Strategy When creating rules that apply to multiple languages: 1. **Add examples for each language**: Create separate positive and negative code examples for JavaScript, TypeScript, Java, etc. 2. **Run assessment for each language**: Packmind assesses each language independently. A rule might be detectable in one language but not another. 3. **Generate programs separately**: Each language gets its own detection program with its own version history. 4. **Activate independently**: You can activate the TypeScript program while keeping the JavaScript program in draft. ## Excluding Files from Analysis You can exclude specific files or directories from lint analysis by creating a `.packmindignore` file. Any file matching a pattern in `.packmindignore` will be skipped entirely during linting. ### File Location Place a `.packmindignore` file at the root of your project. In a **Git repository**, the CLI collects patterns from all `.packmindignore` files found between the linted directory and the Git repository root, merging them together. Outside a Git repository, only the `.packmindignore` in the linted directory is used. ### Syntax * One pattern per line * Lines starting with `#` are comments * Empty lines are ignored * Simple names (e.g., `generated`) match any directory or file with that name at any level * Use `*` to match anything except path separators * Use `**` to match anything including subdirectories ### Example ``` # Ignore all generated code generated # Ignore test fixture files test/fixtures/** # Ignore legacy JavaScript files in src src/*.legacy.js ``` The following paths are **always excluded** by default, even without a `.packmindignore` file: `node_modules`, `dist`, `.git`, `*.min.*` files, and `*.map` files. ## Related Documentation * [Standards Management](/concepts/standards-management): Learn how to create rules and add code examples * [CLI](/tools/cli): Test detection programs from the command line # Automate Repo Updates Source: https://docs.packmind.com/playbook-maintenance/auto-update-artifacts When standards, commands, or skills evolve on Packmind, your repositories don't pick up the changes on their own — someone has to run `packmind install` to refresh the artifacts on disk. This page shows how to delegate that step to a scheduled CI/CD job: the job runs `packmind install` on a cadence you choose and opens a pull/merge request whenever artifacts change, so your team reviews updates instead of remembering to fetch them. **Use this if** you maintain several repositories, or your playbook evolves often. **Manual `packmind install` is fine if** a single maintainer touches the repo and updates are rare. ## How it works A cron-scheduled CI job runs in your repository (typically nightly). The job runs `packmind install`, which pulls the latest standards, commands, and skills. If anything changed, the job commits to a dedicated branch (`packmind-cli-update`) and opens a pull/merge request targeting your default branch. If nothing changed, the job exits silently. If a PR/MR already exists for that branch, new changes are appended instead of duplicating it. ## Set up the workflow Powered by the [`update-packmind-artifacts`](https://github.com/marketplace/actions/update-packmind-artifacts) Marketplace action. ### Prerequisites * A Packmind API key (Packmind → your profile → API keys) * Repository admin rights to add a secret and a workflow ### Add the workflow Create `.github/workflows/nightly-packmind-update.yml`: ```yaml theme={null} name: Nightly Packmind Artifacts Update on: schedule: - cron: '0 2 * * 1-5' # Every weeknight at 02:00 UTC — adjust to your timezone workflow_dispatch: permissions: contents: write pull-requests: write jobs: update: runs-on: ubuntu-latest timeout-minutes: 15 steps: - uses: actions/checkout@v4 with: ref: main # replace with your default branch if different fetch-depth: 0 # required so the action can diff and commit - uses: PackmindHub/update-packmind-artifacts@v1 with: packmind-api-key: ${{ secrets.PACKMIND_API_KEY }} ``` ### Configure the API key secret In your repository: **Settings → Secrets and variables → Actions → New repository secret**. | Secret name | Value | | - | - | | `PACKMIND_API_KEY` | The API key from your Packmind user profile | Common action inputs (branch name, PR title, target branch, Node version) are documented on the [Marketplace listing](https://github.com/marketplace/actions/update-packmind-artifacts). ### Verify it works Don't wait for the next scheduled run. Go to **Actions → Nightly Packmind Artifacts Update → Run workflow** and trigger it manually. Within a minute or two you should see either a new PR titled `chore(packmind): nightly artifacts update`, or a successful run with the message `No artifact changes`. ### Prerequisites * A Packmind API key (Packmind → your profile → API keys) * Maintainer or Owner access to create a Project Access Token ### Add the workflow Place this file at the **root of your repository** as `.gitlab-ci.yml`. If you already have one, merge the `nightly-packmind-update` job into your existing `stages` and jobs. ```yaml theme={null} stages: - update nightly-packmind-update: stage: update image: node:22.17.0 timeout: 15 minutes variables: GIT_DEPTH: 0 # full history required to commit and diff rules: - if: $CI_PIPELINE_SOURCE == "web" # manual "Run pipeline" - if: $CI_PIPELINE_SOURCE == "schedule" # cron schedule script: - git config user.name "packmind-bot" - git config user.email "packmind-bot@users.noreply.gitlab.com" - git remote set-url origin "https://oauth2:${PACKMIND_BOT_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git" - | if git ls-remote --exit-code --heads origin packmind-cli-update; then git fetch origin packmind-cli-update git checkout packmind-cli-update git merge --no-edit origin/main || true else git checkout -b packmind-cli-update fi - npm install -g @packmind/cli - packmind install - | if [ -z "$(git status --porcelain)" ]; then echo "No artifact changes — skipping commit/push." exit 0 fi - git add -A - 'git commit -m "chore(packmind): nightly artifacts update"' - | git push origin packmind-cli-update \ -o merge_request.create \ -o merge_request.target=${CI_DEFAULT_BRANCH} \ -o merge_request.title="chore(packmind): nightly artifacts update" ``` The reference template is also available in the [Packmind repository](https://github.com/PackmindHub/packmind/blob/main/auto-update/.gitlab-ci.yml). ### Configure the CI variables In **Settings → CI/CD → Variables**, add both variables and mark them as **Masked**: | Variable | Value | | - | - | | `PACKMIND_API_KEY` | The API key from your Packmind user profile | | `PACKMIND_BOT_TOKEN` | A Project Access Token with `write_repository` and `api` scopes, role ≥ Developer | To create the token: **Settings → Access Tokens → Add new token** with scopes `write_repository` and `api`. ### Schedule the job In **Settings → CI/CD → Pipeline schedules → Add new schedule**, set: * **Interval pattern**: `0 2 * * 1-5` (weeknights at 02:00 UTC — adjust to your timezone) * **Target branch**: your default branch ### Verify it works Don't wait for the schedule. Go to **Build → Pipelines → Run pipeline**, select your default branch and click **Run pipeline**. Within a couple of minutes you should see either a new merge request titled `chore(packmind): nightly artifacts update`, or job logs ending with `No artifact changes — skipping commit/push.` ## Choose a schedule The example uses `0 2 * * 1-5` — every weeknight at 02:00 UTC (03:00 Paris in winter, 04:00 Paris in summer, 21:00 New York the previous day). Adjust the cron expression to land outside your team's working hours so PRs are waiting when people come online. **How often?** Nightly fits most teams. Run hourly only if your playbook changes multiple times a day; running more frequently than your playbook evolves just creates noise. ## Security considerations The job has write access to your repository and uses an API key tied to your Packmind account. Treat both with care. * Always store the API key and bot token as CI/CD secrets — never commit them. * Where possible, generate the Packmind API key from a dedicated service account rather than a personal account, so reviews and audits stay clean if people leave the team. * On GitLab, scope the Project Access Token to the minimum role (Developer) and rotate it periodically. * The opened PR/MR is reviewed by a human — keep that step in your branch protection rules so artifact changes don't auto-merge. ## Troubleshooting Either no artifacts changed (check the logs for `No artifact changes`), or the job lacked write permissions. On GitHub, verify the `permissions:` block includes `contents: write` and `pull-requests: write`. On GitLab, verify the Project Access Token has `write_repository` and `api` scopes and a role of at least Developer. The API key is missing, mistyped, or revoked. Regenerate it from your Packmind profile and update the `PACKMIND_API_KEY` secret. Make sure the variable name matches exactly. The `packmind-cli-update` branch may have been edited manually, or merged into the default branch without closing the PR. Close the existing PR/MR, delete the `packmind-cli-update` branch, and re-run the job — it will recreate the branch from your default branch. The GitHub example pins `ref: main` in the checkout step. Replace it with the name of your default branch. On GitLab, `CI_DEFAULT_BRANCH` is auto-detected, so no change is needed. ## Related documentation * [Distribution](/governance/distribution) — Distribute artifacts to your team manually or via CLI * [Updating Your Playbook](/playbook-maintenance/updating-your-playbook) — Other ways to update artifacts * [CLI Reference](/tools/cli) — Full reference for `packmind install` and other commands # Change Proposals Source: https://docs.packmind.com/playbook-maintenance/change-proposals **Enterprise Feature** — This functionality is only available in the **Enterprise** version of Packmind. Change proposals are one of two ways to update your playbook. Unlike [direct updates](/playbook-maintenance/updating-your-playbook#direct-updates), change proposals require team review before changes are applied. Change Proposals require **CLI version 0.23.0 or later**. Run `packmind --version` to check your version — on 0.23.x the command is `packmind-cli --version`, which is the only name that install has — and see [CLI Installation](/tools/cli#installation) to upgrade. ## What are Change Proposals? Change Proposals enable users to propose modifications to distributed artifacts (standards, commands, skills) directly from their local environment. Once submitted, proposals are reviewed and approved through the Packmind UI, ensuring that changes go through a controlled review process before being applied. There are two ways to submit change proposals: 1. **Use the `packmind-update-playbook` skill** — the skill analyzes your coding session, identifies relevant changes, and submits proposals on your behalf automatically. This is the recommended approach. 2. **Edit local files manually and use the CLI** — modify distributed artifact files directly, then use `packmind playbook` commands to stage and submit your changes. ## Submitting Changes with the `packmind-update-playbook` Skill The `packmind-update-playbook` skill automates the entire process. It analyzes your coding session, identifies what changed, and submits change proposals on your behalf. It follows a four-phase workflow: 1. **Summarize the session** — extracts what was built, what patterns emerged, and what decisions were made. 2. **Analyze existing artifacts** — evaluates your current standards, commands, and skills against the session context. 3. **Propose a change report** — presents a numbered list of proposed updates, new artifacts, or deprecations for you to approve. 4. **Apply approved changes** — edits local files and submits proposals for review on Packmind. The skill activates automatically when you use phrases like "update the playbook", "sync standards", or "check if we need new standards". It can also be triggered after coding sessions where new patterns or conventions emerged. Learn more about how skills work in the [Skills Management](/concepts/skills-management) section. ## Submitting Changes with the CLI The CLI requires a **git repository with a remote configured**. If no git repository or remote is detected, the command will fail with an error. Make sure you also have the CLI installed and configured — see [CLI setup](/tools/cli) for details. Local changes must be made on files deployed by Packmind during distribution — these include files in the `.packmind/` directory as well as agent-specific directories such as `.claude/`, `.github/`, `.cursor/`, and others depending on your enabled AI agents (see [Distribute artifacts](/governance/distribution) for the full list). ### Typical workflow The `playbook` command uses a git-like staging workflow. You stage changes individually, then submit them all at once: 1. Edit local artifact files (standards, commands, or skills) 2. Run `packmind playbook diff` to preview what changed 3. Run `packmind playbook status` to see staged and untracked changes 4. Run `packmind playbook add ` to stage the changes you want to submit 5. Run `packmind playbook submit -m "message"` to submit staged changes as proposals ### View local changes To see what local changes differ from the published versions: ```bash theme={null} packmind playbook diff ``` To include changes that have already been submitted: ```bash theme={null} packmind playbook diff --include-submitted ``` To limit the analysis to a specific path: ```bash theme={null} packmind playbook diff -p .claude/rules/ ``` ### Check playbook status To see which changes are staged for submission and which are untracked: ```bash theme={null} packmind playbook status ``` **Example output:** ``` Changes to be submitted: - Standard "Error Handling" (updated) .claude/rules/error-handling.md Changes not tracked: - Command "Deploy" (modified) .claude/commands/deploy.md Use `packmind playbook add ` to track them ``` ### Stage changes To stage a local artifact change for submission: ```bash theme={null} packmind playbook add ``` This stages the artifact but does **not** submit it. Packmind automatically detects whether the change is a creation or an update by comparing with the deployed version. The file must be located in a recognized artifact directory: | Artifact type | Recognized directories | | - | - | | **Commands** | `.claude/commands/`, `.cursor/commands/`, `.github/prompts/`, `.continue/prompts/`, `.packmind/commands/` | | **Standards** | `.claude/rules/`, `.cursor/rules/`, `.github/instructions/`, `.continue/rules/`, `.kiro/steering/`, `.packmind/standards/` | | **Skills** | `.claude/skills/`, `.cursor/skills/`, `.github/skills/`, `.gitlab/duo/skills/`, `.opencode/skills/`, `.agents/skills/`, `.kiro/skills/` | #### File format requirements * **Commands**: File must not be empty. Frontmatter with `name:` is optional. * **Standards**: Must start with a markdown heading (`# Name`) followed by content. Example: ```md theme={null} # My standard name Content goes here... ``` * **Skills**: Path must point to a directory containing a `SKILL.md` with valid frontmatter (`name`, `description`) and a non-empty body. #### When it won't work The command will fail if: * The file is not inside a recognized artifact directory * The path points to a directory instead of a file (for commands and standards) * The file content is invalid (empty command, standard without rules, skill missing `SKILL.md`) ### Stage removal To stage an artifact for removal from packages: ```bash theme={null} packmind playbook rm ``` The artifact must have been distributed by Packmind. The command will fail if the artifact was not deployed by Packmind (error: *"This file was not distributed using packmind"*). After submitting with `playbook submit`, the removal proposal appears in the **Review changes** UI. The reviewer can either dismiss the proposal or choose **Remove from packages**. When removing, a dialog lets the reviewer select which packages to remove the artifact from, showing which packages are affected before applying the change. #### Conflicts with removal proposals If someone submits a modification and someone else submits a removal for the same artifact, both proposals appear in the review UI. Accepted removal proposals block conflicting proposals on the same artifact. ### Unstage changes To remove a previously staged change without submitting it: ```bash theme={null} packmind playbook unstage ``` ### Submit staged changes To submit all staged changes as proposals: ```bash theme={null} packmind playbook submit -m "Clarify error handling rules for API endpoints" ``` The message has a maximum length of 1024 characters. If you omit the `-m` flag in interactive mode, an editor will open for you to write the message. #### Duplicate name detection Before submitting, Packmind checks whether any artifact you are creating already exists in the target [space](/concepts/spaces) (by name, case-insensitive). If a duplicate is found, the submission is rejected with an error: ``` Error: A standard named "My Standard" already exists in this space. Use "playbook unstage" to remove it or rename the artifact. ``` To resolve this, either rename your local artifact file or run `packmind playbook unstage ` to remove it from the staged changes. If you see an error like **Failed to submit "": is outdated, please run packmind install to update it**, it means the local artifact version is stale. Run `packmind install` to fetch the latest versions, reapply your changes, and submit again. ## Important: Pending Changes and the Install Command While changes are pending (not yet accepted), running `packmind install` will overwrite your local modifications with the server version. This will erase any unstaged or unsubmitted changes. Always submit your staged changes with `packmind playbook submit` before running `packmind install` to avoid losing your work. ## Reviewing Change Proposals in the UI Once changes have been submitted, they can be reviewed in the Packmind web interface: 1. Navigate to the **Review changes** module from the sidebar menu 2. Proposals are grouped by artifact (standard, command, or skill) 3. Each proposal shows the modification type and a diff view highlighting additions and removals 4. Review each proposal and choose to **accept** or **dismiss** it 5. Click **Apply changes** to create a new version of the artifact with the accepted changes ### Editing a Proposal Before Accepting Reviewers can edit a change proposal's proposed value before accepting it. This is useful when a proposal is mostly correct but needs minor adjustments — for example, fixing a typo in a proposed name or refining the wording of a description. To edit a proposal: 1. Click the **edit** button on the proposal card 2. Modify the proposed value in the input field 3. Click **Save & Accept** to accept the proposal with your edits, or **Cancel** to discard your changes Editing is available for name, description, and prompt updates on standards, commands, and skills. Other proposal types (rule changes, skill file updates, removals, and creations) cannot be edited. Once a proposal has been edited: * An **Edited** badge appears on the proposal card * The card shows both the **original proposal** (collapsed by default) and the **edited** version, so reviewers can compare the two * A **Reset to original** button lets you discard the edit and revert to the original proposed value * If you **undo** the acceptance (move the proposal back to "To review"), the edit is discarded Editing a proposal may also trigger **conflict recomputation** — if the edited value introduces or resolves a conflict with another pending proposal, the conflict status is updated automatically. ## Conflict Management When an artifact moves on while a change proposal is still pending — because a new version was published, or because another proposal was accepted — Packmind re-checks the proposal against the latest content instead of discarding it. Most proposals survive. If the proposal's edit and the new content touch different parts of the artifact, Packmind merges them automatically: the proposal stays applicable, and the diff shown in the review UI is rebased onto the current content, so what you see is exactly what accepting it would produce. A proposal is only marked **Outdated** when its edit genuinely collides with the new content — that is, when both changed the same words. Those cannot be applied as-is; the submitter needs to rebase their changes on the latest version and submit a new proposal. The same rule applies to the warning shown when you edit an artifact that has pending proposals. Packmind checks your unsaved draft against each pending proposal and tells you how many would actually become outdated — often none. While reviewing, accepting one proposal immediately re-checks the others against your selection. A proposal that would collide with something you have already accepted is flagged as **Conflicting** until you undo that acceptance. # Update from External Sources Source: https://docs.packmind.com/playbook-maintenance/update-from-external-sources Your team's coding knowledge doesn't live only in the codebase. Valuable conventions, decisions, and best practices are scattered across pull request reviews, Slack discussions, issue trackers, and documentation wikis. Packmind can automatically mine these external sources using AI agent skills and [MCP servers](https://modelcontextprotocol.io/), classify findings for playbook relevance, and submit them as [change proposals](/playbook-maintenance/change-proposals) for your team to review. Looking to do a one-time import from a knowledge base? See [Import from Confluence, Notion and more](/tools/import-from-knowledge-base). ## Why Mine External Sources? * **Knowledge is scattered** — PR review comments, Slack threads, Jira issues, and wiki pages all contain insights that should live in the playbook. * **Manual updates are easy to forget** — Without automation, new conventions agreed upon in a PR review or a Slack discussion may never make it into the playbook. * **Continuous mining keeps the playbook current** — Regularly scanning external sources ensures emerging patterns and decisions are captured as they happen. * **Change proposals ensure human review** — Every finding goes through a [change proposal](/playbook-maintenance/change-proposals), so your team stays in control of what enters the playbook. ## How It Works The workflow follows a three-stage pipeline: 1. **Fetch** — A source skill queries an external tool through its MCP server (e.g., fetching merged PR review comments from GitHub, or retrieving recent channel messages from Slack). 2. **Classify** — The AI agent analyzes the fetched data and identifies items relevant to coding conventions, best practices, architectural decisions, or recurring patterns. 3. **Update** — Classified findings are handed off to the `packmind-update-playbook` skill, which creates [change proposals](/playbook-maintenance/change-proposals) in Packmind — standards, commands, or skills depending on the nature of each finding. This workflow is AI agent agnostic. It works with any agent that supports MCP — Claude Code, GitHub Copilot, Cursor, Windsurf, and others. ## Supported Sources | Source | What is mined | | - | - | | **GitHub PR Comments** | Review comments from merged pull requests | | **Slack Conversations** | Channel discussions and threaded messages | | **Jira Issues** | Resolved issues and their comments | | **GitLab MR Comments** | Review comments from merged merge requests | | **Confluence Documentation** | Pages and spaces | | **Notion Documentation** | Pages and databases | These are example use cases. Any tool that exposes an MCP server can be used as a source — see [Adding Custom Sources](#adding-custom-sources) below. ## Example Skills Repository The [demo-use-case-skills](https://github.com/PackmindHub/demo-use-case-skills) repository is a **public showcase** of example source skills. None of these skills are built into or available within the Packmind app — they are provided as open-source examples that teams can use as-is, adapt to their needs, or draw inspiration from when building their own. Inside you will find: * **Source skills** for each integration — one skill per external source, each handling data fetching, noise filtering, and relevance classification. * **Shared skills** — `packmind-update-playbook` (creates change proposals from findings) and `packmind-cli-list-commands` (prevents duplicate artifacts). * **CI workflow examples** — GitHub Actions configurations for running source skills on a schedule, so your playbook is updated automatically without manual intervention. Each integration folder includes its own README with setup instructions, MCP server configuration, and usage examples. ## Adding Custom Sources The architecture is extensible by design. The [example skills repository](https://github.com/PackmindHub/demo-use-case-skills) demonstrates how to build source skills, and you can follow the same pattern to create your own. To add a new external source, create a skill that fetches data from the source's MCP server, classifies findings for playbook relevance, and hands them off to `packmind-update-playbook`. Any tool with an MCP server can become a source — monitoring tools, design systems, internal APIs, and more. ## Learn More * [Change Proposals](/playbook-maintenance/change-proposals) — How change proposals are reviewed and applied * [Updating Your Playbook](/playbook-maintenance/updating-your-playbook) — Overview of all playbook update workflows * [Import from Confluence, Notion and more](/tools/import-from-knowledge-base) — One-time import from knowledge bases * [Skills Management](/concepts/skills-management) — How skills work and how to create them * [CLI Reference](/tools/cli) — CLI installation and commands * [Demo Use Case Skills](https://github.com/PackmindHub/demo-use-case-skills) — Example source skills repository # Updating Your Playbook Source: https://docs.packmind.com/playbook-maintenance/updating-your-playbook Your playbook evolves alongside your codebase. Packmind supports two workflows for updating artifacts (standards, commands, and skills): * **Direct updates** — create a new artifact version immediately, without team review. * **[Change proposals](/playbook-maintenance/change-proposals)** — submit changes for team review before they are applied, via the CLI or the `packmind-update-playbook` skill. ## Direct Updates Direct updates create a new artifact version immediately, without requiring team review. ### Using the UI Standards, commands, and skills can be updated directly in the Packmind web interface. Open the artifact you want to edit, make your changes, and save to create a new version immediately. ### Using the CLI Standards, commands and skills can be directly imported or updated using the CLI: ```bash theme={null} packmind playbook add packmind playbook submit --no-review ``` This creates a new version of the artifact (standard, command or skill) immediately without going through a change proposal. See the [CLI reference](/tools/cli) and [Skills Management](/concepts/skills-management) for details. ## Change Proposals For changes that should be reviewed by the team before being applied, use [Change Proposals](/playbook-maintenance/change-proposals). This workflow lets you submit modifications from your local environment — either manually with `packmind playbook` commands, or automatically with the `packmind-update-playbook` skill. ## Choosing the Right Workflow | | Direct updates | Change proposals | | - | - | - | | **Best for** | You own the artifact and want immediate effect | Changes that should be reviewed by the team | | **Review** | None — new version is created immediately | Team reviews and approves in the Packmind UI | | **How** | Web interface or `packmind playbook add` | `packmind-update-playbook` skill or `packmind playbook` commands | | **Supported artifacts** | All artifact types | All artifact types | # Security & Privacy Source: https://docs.packmind.com/security/security-privacy ## Overview This document provides comprehensive information about how Packmind handles data, implements security measures, and integrates with AI services. **This page is dedicated mainly to the Cloud version**. For information about security and privacy in self-hosted and on-premise deployments, please see [Security & Privacy (Self-Hosted)](/security/security-privacy-self-hosted). ## Data Handling ### Functional Data (Business Content) Packmind stores information necessary for building the **Engineering Playbook** used by AI agents: * **Coding rule descriptions** * Text describing best practices * Code snippets illustrating: * Correct implementation * Incorrect practices * This data originates from **the client's codebase** and is generated manually by users. ### Personal Data Packmind stores **only** the following personal data: * **Email address** of the user (for authentication) ### External Service Credentials Stored only if the client configures these integrations: * GitHub / GitLab connection information (access tokens) * LLM provider access keys, including: * OpenAI * Anthropic * Azure OpenAI * These credentials enable advanced features related to AI agents. Packmind **never uses** this data for any other internal purposes. ## Data Origin & Authentication ### Data Source All data comes from **the client environment**: * Users provide data to Packmind via the **CLI or AI coding assistants** * No automated or bulk imports (e.g., CSV) are performed * All data is transmitted **manually, voluntarily, and intentionally** ### Authentication * Each user must individually authenticate to Packmind * Web interface authentication uses username/password. Single sign-on is also available with Google, Microsoft or GitHub. ## Data Retention & Storage ### Retention Policy * Data is retained **as long as the client organization is active on the cloud platform** * Data can be permanently deleted upon request * In self-hosted deployments, the client has full control over retention ### Architecture & Deployment Packmind offers two deployment modes: #### Cloud Mode (Hosted by Packmind) * Infrastructure on **Microsoft Azure AKS** (Kubernetes) * Hosting in **France region** * Database, backups, and replications located **only in Europe** * Deployment planned soon in a **US region** #### Self-Hosted Mode * Deployment options: * via Docker Compose * via Kubernetes (open source Helm chart) * The client becomes responsible for: * network and isolation * secret management * monitoring ## Security Measures ### Encryption * **TLS 1.3** for all traffic in transit on the Cloud platform * **AES 256** encryption at rest for all data * **AES 256** encryption for database backups ### Compliance Packmind is certified **SOC 2 Type II**. Feel free to contact us to request a copy of the report at contact\_at\_packmind.com. ### Sub-processors | Name | Website | Purpose | Data Processed | Region of Data Hosting | | - | - | - | - | - | | Microsoft Azure | [azure.microsoft.com](https://azure.microsoft.com) | Cloud hosting | All application data | France Central (EU) | | OpenAI | [openai.com](https://openai.com) | LLM provider | LLM prompts and responses | United States | | WorkOS | [workos.com](https://workos.com) | Social login authentication | Email addresses | United States | | Brevo | [brevo.com](https://www.brevo.com) | SMTP relay | Email addresses | Belgium (EU) | | Crisp | [crisp.chat](https://crisp.chat) | Customer Support | Email addresses | Netherlands (EU) | ### Personal Data Requests Packmind only stores email addresses as personal information. Reach us at dpo\_at\_packmind.com if you have any request regarding your current personal data we own, or any deletion request. ## AI & LLM Integration ### Default Provider By default, Packmind uses **OpenAI** as the LLM provider for all organizations. You can configure your own LLM provider. ### Data Privacy & Usage * **Training**: Your data is **not used by OpenAI for training any models** * **Storage by OpenAI**: LLM prompts and responses are **not stored by OpenAI** * **Storage by Packmind**: Inputs/outputs from models may be stored by Packmind for: * Observability * Analysis * Quality improvement of use cases * **Metadata**: Only metadata such as the number of input and output tokens is stored ### No Internal AI Model Development * Packmind **does not develop its own AI models** * Client data: * is never used to train models * does not serve to build internal datasets * is not transmitted to third parties for AI usage ### AI Interaction Nature * Uses **completion endpoints** (prompt / sequences of prompts) * Does **not** use: * Vector storage * Embeddings * Vector databases ## Protocols & Security * All communications use the **HTTPS** protocol * Infrastructure is secured and monitored via Azure * Packmind code is **open source** to allow auditing of behavior # Security & Privacy (Self-Hosted) Source: https://docs.packmind.com/security/security-privacy-self-hosted Understand your responsibilities and control over data when running Packmind on your own infrastructure. ## Overview When you install Packmind on your own servers, **you have complete control over your data**. Nothing is sent to Packmind's cloud services. This page explains what this means for you and what you're responsible for managing. For information about Packmind Cloud security and privacy, see [Security & Privacy](/security/security-privacy). ## Your Data Control ### Complete Local Control When you run Packmind on your infrastructure: * **All your data stays local** - Nothing is sent to Packmind's cloud application * **You control everything** - Your database, backups, and all data remain within your infrastructure * **Air-gapped deployments supported** - You can run Packmind entirely offline within your local network ### No Data Sharing with Packmind Packmind has **no access** to your self-hosted installation: * We cannot see what you do in your Packmind instance * We do not have access to your database or any operational data * All your data remains entirely within your infrastructure ## Your Responsibilities When you run Packmind self-hosted, you are responsible for: ### Data Backups You must create and maintain your own backup strategy. Packmind does not automatically back up your data. ### Data Encryption You are responsible for encrypting your data: * Data stored in your database (encryption at rest) * Data transmitted between services (encryption in transit) ### Database Security You manage and secure your database. This includes: * Setting strong passwords * Controlling who has access * Keeping your database updated ### Network Security You control: * Who can access your Packmind instance * Firewall rules and network isolation * How services communicate within your network ### API Keys and Credentials You manage all secrets and credentials: * API keys for AI providers * Access tokens for Git repositories * Database passwords and other credentials ### Monitoring and Maintenance You are responsible for: * Monitoring your Packmind instance * Keeping components updated * Reviewing logs for issues ## Connecting External Services ### Git Repositories When you connect GitLab, GitHub, or other Git repositories: * All repository data stays on your infrastructure * No repository information is sent to Packmind servers * You control all access tokens and credentials * Everything happens within your network ### AI Providers When you connect AI providers like OpenAI, Anthropic, or Azure OpenAI: * You use **your own API keys** - Packmind never sees these credentials * You are responsible for reviewing each provider's: * Data processing and retention policies * Terms of service * Privacy policies * Compliance certifications (if needed for your use case) * All API calls go directly from your infrastructure to your chosen provider ## Air-Gapped Deployments You can run Packmind in environments with no internet connection: * The application runs entirely within your local network * No connection to external Packmind services is needed * All functionality works offline * You can deploy using Docker Compose or Kubernetes in your isolated network To deploy in an air-gapped environment, ensure you have all required components available locally before starting the installation. ## Data Retention You have complete control over how long to keep your data: * You decide when to delete data * You set your own retention policies * Packmind does not automatically delete any data ## Compliance When running Packmind self-hosted: * You are responsible for meeting compliance requirements (GDPR, HIPAA, SOC 2, etc.) * Packmind's SOC 2 Type II certification applies to the cloud version only * You must implement and maintain your own compliance measures * All data processing happens within your infrastructure under your control ## Open Source Transparency Packmind is open source, which means you can: * Review the code to understand exactly what it does * Verify how your data is handled * Customize the deployment for your security needs * Contribute improvements to the project ## Related Documentation * [Install Packmind on your server](/getting-started/gs-install-self-hosted) - Setup instructions for self-hosted deployments * [Security & Privacy](/security/security-privacy) - Security information for Packmind Cloud # CLI: Command-Line Interface Source: https://docs.packmind.com/tools/cli ## Overview **The command is `packmind`** — The older `packmind-cli` name still works, but it is deprecated and will be removed in a future release. Update any scripts, aliases, or CI jobs that still call `packmind-cli`. The Packmind CLI provides the following commands: * **`init`** - Initialize Packmind in your project (configure agents + install skills) * **`git track`** - Set the repository and branch Packmind tracks for your project (`--branch` to name it explicitly) * **`git untrack`** - Remove Packmind's tracking of the current repository * **`git info`** - Show whether Packmind tracks the current repository, and on which branch * **`config agents setup`** - Configure which AI coding agents to generate artifacts for (interactive) * **`config agents list`** - List configured agents across `packmind.json` files * **`config agents add`** - Add coding agents to `packmind.json` files * **`config agents rm`** - Remove coding agents from `packmind.json` files * **`login`** - Authenticate with your Packmind instance * **`logout`** - Clear stored credentials * **`whoami`** - Show current authentication status * **`install`** - Download packages locally * **`uninstall`** - Remove packages from your project * **`distribution record`** - Send your local `packmind-lock.json` files to Packmind as what each target runs * **`lint`** - Run detection programs (Enterprise only) * **`playbook diff`** - Show differences between local files and Packmind artefacts * **`playbook add`** - Stage a change between local files and Packmind artefacts * **`playbook submit`** - Submit local changes to Packmind * **`skills init`** - Install default Packmind skills locally * **`skills list`** - List all skills in your organization * **`standards list`** - List all standards in your organization * **`commands list`** - List all commands in your organization * **`spaces list`** - List all spaces in your organization * **`packages create`** - Create a new package * **`packages add`** - Add standards, commands, or skills to a package * **`packages move`** - Move standards, commands, or skills into a package, removing them from every other one * **`packages remove`** - Remove standards, commands, or skills from a package * **`packages list`** - List all packages in your organization * **`plugins render`** - Render a Packmind package as a Claude Code or GitHub Copilot plugin * **`plugins delete`** - Delete a rendered Claude Code or GitHub Copilot plugin from this workspace * **`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. Sets up your PATH environment variable Simply copy the provided command and paste it into your terminal. The script handles everything automatically. **Why this is recommended** — The one-click install eliminates manual steps by combining installation and authentication in a single command. ### Alternative: npm Package **Node.js 22 or higher required**. **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 login ``` 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-cli ``` The Homebrew formula is still named `packmind-cli`, and it installs the executable under that name. If `packmind` is not found after a Homebrew install, use `packmind-cli`. ### 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 ``` **Choosing an Installation Method** — Use **one-click install** for the simplest experience with automatic authentication. 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. ## 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` set as an environment variable, you'll need to unset it separately: ```bash theme={null} unset PACKMIND_API_KEY ``` ### Whoami Command Check your current authentication status: ```bash theme={null} packmind whoami ``` This displays: * Connected host * Organization name * User name * Credential expiration status * Where your credentials come from (environment variable or credentials file) ### API Key Authentication (PACKMIND\_API\_KEY) You can authenticate using the `PACKMIND_API_KEY` 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` environment variable with your API key: ```bash theme={null} export PACKMIND_API_KEY="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="your-api-key-here"' >> ~/.zshrc source ~/.zshrc ``` #### CI/CD Example (GitHub Actions) ```yaml theme={null} - name: Install Packmind packages env: PACKMIND_API_KEY: ${{ secrets.PACKMIND_API_KEY }} run: packmind install ``` **Credential Priority** — When both a credentials file and the `PACKMIND_API_KEY` environment variable exist, the environment variable takes precedence. ## 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 these main actions: 1. **Configures AI agents** - Interactively select which AI coding agents to generate artifacts for 2. **Installs default skills** - The `packmind-onboard` and `packmind-update-playbook` skills 3. **Offers to track this repository** - Prompts you to set the current repository and branch as the one Packmind tracks (you can confirm or skip) ### 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. Ask whether to track the current repository and branch (you can confirm or skip) 5. 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 ``` **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. ## Git Command Manage which repository and branch Packmind tracks for your project. The tracked branch is the anchor Packmind uses to attribute governance and adoption activity, so declaring it tells Packmind where to follow your team's work. Only installs that run on the tracked repository and branch are recorded — see [Distribution Recording](#distribution-recording-tracked-repository-and-branch). The command has three subcommands: `git track` to set or move the tracked branch, `git untrack` to remove tracking, and `git info` to see the current state. **Organization admins only** — Only organization admins can set, move or remove the tracked branch. If you are not an admin, the command reports that you cannot change the tracked branch. `git info` only reads, so anyone can run it. **Renamed** — These used to be the top-level `packmind track` and `packmind untrack` commands. The old names now exit with an error naming their replacement. ### Git Track Set which repository and branch Packmind tracks for your project. #### Track the Current Branch Run the command from inside your project to track the current repository and branch: ```bash theme={null} packmind git track ``` Packmind derives the repository and branch from your local git remote and current branch, then asks you to confirm before setting it: ``` Track my-org/my-repo on branch dev? (y/N) Packmind now tracks my-org/my-repo on branch dev. ``` If the branch you are on is already the tracked branch, the command reports that it is already tracked and makes no change. If a **different** branch is already tracked, the command stops and tells you to use `--update` to move it: ``` Repository my-org/my-repo is already tracked on branch main. Run `packmind git track --update` to move it to dev. ``` #### Track a Specific Branch Use `--branch` to name the branch explicitly instead of tracking whichever one you have checked out: ```bash theme={null} packmind git track --branch main ``` This is useful when you are working on a feature branch but want governance anchored to your default branch — you no longer have to `git checkout main` first. The branch does not need to be checked out locally. ``` Track my-org/my-repo on branch main? (y/N) Packmind now tracks my-org/my-repo on branch main. ``` `--branch` works with `--update` too, to move tracking to a branch you are not currently on. The branch has to exist, though. A name Packmind cannot find in your repository is refused instead of being tracked, so a typo cannot leave you waiting for distributions that are never recorded: ``` Branch mian does not exist in my-org/my-repo. Check the spelling, or run `git fetch` first if the branch only exists on the remote. ``` Both local branches and branches you have fetched from the remote count. A branch created on the remote since your last fetch is unknown locally — run `git fetch` and try again. #### When No Branch Is Checked Out Mid-rebase, after `git checkout `, or in a CI job that checked out a pull request merge ref, your repository has no current branch — Git calls this a detached `HEAD`. There is nothing to track in that state, so the command stops instead of tracking a branch called `HEAD`: ``` No branch is checked out for my-org/my-repo — HEAD is detached. Check a branch out, or name one with `packmind git track --branch `. ``` Naming the branch with `--branch` works as usual, so tracking can still be set from a detached checkout. #### Move the Tracked Branch Use the `--update` flag to move tracking to your current branch when a different branch is already tracked. Packmind asks you to confirm the change before applying it: ```bash theme={null} packmind git track --update ``` ``` Change the tracked branch for my-org/my-repo from main to dev? (y/N) Tracked branch for my-org/my-repo changed from main to dev. ``` Add `--branch` to move tracking to a branch other than the one you have checked out: ```bash theme={null} packmind git track --update --branch main ``` If you cancel the prompt, the tracked branch is left unchanged. Moving the tracked branch is **reversible**: the distributions recorded on the branch you leave are kept, they simply stop being displayed, and they reappear if you move tracking back. See [Distribution History and the Tracked Branch](/governance/distribution#distribution-history-and-the-tracked-branch). If nothing is tracked yet, `--update` has nothing to move and points you to the commands that start tracking: ``` Nothing is tracked yet — run `packmind init` or `packmind git track` to start tracking. ``` **During onboarding** — `packmind init` also offers to track the current repository and branch, so you can set the anchor as part of your first-time setup. Use `packmind git track` later to set or move it. ### Git Untrack Take a repository out of Packmind's governance views. Tracking applies to the repository, so `git untrack` takes no branch — it removes whichever branch is currently tracked. **Organization admins only** — Only organization admins can remove tracking. Run it from a clone of the repository. Packmind asks you to confirm first, and names the tracked branch so you can see what you are about to remove: ```bash theme={null} packmind git untrack ``` ``` Stop tracking my-org/my-repo? Packmind currently tracks branch main. (y/N) Packmind no longer tracks my-org/my-repo. Distributions recorded on branch main are kept and reappear if you track it again. ``` The repository disappears from Distribution History and the Deployments overview. **Nothing is deleted** — run `packmind git track` on the same branch again and the whole history comes back, with new distributions appended. See [Removing Tracking](/governance/distribution#removing-tracking). While the repository is untracked, `packmind install` behaves as it does for a repository that was never tracked: it completes locally and tells you the distribution was not recorded. Running `git untrack` on a repository that is not tracked changes nothing and reports it, exiting successfully so the command is safe to repeat: ``` Repository is not tracked in 'my-organization' organization ``` ### Git Info Check what Packmind tracks for the repository you are in, without changing anything: ```bash theme={null} packmind git info ``` When the repository is tracked and you are on the tracked branch: ``` Packmind tracks my-org/my-repo on branch 'main'. ``` When the repository is tracked but you are on **another** branch, the command adds a warning, because installs you run from here are not recorded: ``` Packmind tracks my-org/my-repo on branch 'main'. You are on 'dev', so distributions from here are not recorded. Run `packmind git track --update` to move tracking to 'dev'. ``` When the repository is not tracked at all: ``` my-org/my-repo is not tracked in Packmind. Run `packmind git track` to track branch 'main'. ``` All three are answers rather than failures, so the command succeeds in each case. It only fails when it cannot answer — outside a git repository, with no git remote, or when you are not signed in. ### Troubleshooting * **Problem**: `Repository tracking is not available for your account.` * **Solution**: The feature is not enabled for your organization yet. Contact your Packmind administrator. * **Problem**: The command reports you are not logged in. * **Solution**: Run `packmind login` first, then retry. * **Problem**: The command cannot determine the repository or branch. * **Solution**: Run it from inside a git repository that has a configured remote and a checked-out branch. * **Problem**: `Command "packmind track" has been removed.` * **Solution**: Use `packmind git track` (or `packmind git untrack` in place of `packmind track --remove`). ## Config Command Configure Packmind settings. ### Config Agents Manage AI coding agents configured in your `packmind.json` files. The `config agents` command provides subcommands for interactive setup, listing, adding, and removing agents. #### Config Agents Setup Configure which AI coding agents to generate artifacts for via an interactive prompt: ```bash theme={null} packmind config agents setup ``` 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/duo/` directory * **OpenCode** - Artifacts in `.opencode/` directory * **Codex** - Artifacts in `.agents/` directory * **Kiro** - Artifacts in `.kiro/` directory The command auto-detects existing agent configurations in your project and pre-selects them. Your selection is saved to `packmind.json`. **Auto-detection** — If you already have agent configuration files (like `.cursor/` or `.claude/`), they will be automatically pre-selected when you run this command. #### Config Agents List Display all configured coding agents across `packmind.json` files in a matrix view: ```bash theme={null} packmind config agents list ``` The output shows a matrix with file paths as rows and agent names as columns, using checkmarks (✓) and dashes (-) to indicate which agents are configured in each file. Each file also shows its source — whether agents are configured locally (via the `agents` property in `packmind.json`) or inherited from organization settings. Use `--path` to scope the listing to a specific directory: ```bash theme={null} packmind config agents list --path ./apps/api ``` #### Config Agents Add Add one or more coding agents to all `packmind.json` files: ```bash theme={null} packmind config agents add claude cursor ``` Use `--path` to target a specific directory: ```bash theme={null} packmind config agents add --path ./packages/core claude ``` If the targeted files currently inherit agent configuration from organization settings, a confirmation prompt warns that adding local agents will override the organization-level defaults. #### Config Agents Remove Remove one or more coding agents from all `packmind.json` files: ```bash theme={null} packmind config agents rm cursor copilot ``` Use `--path` to target a specific directory: ```bash theme={null} packmind config agents rm --path ./apps/frontend claude ``` When all agents are removed from a file, the `agents` property is deleted entirely and the file reverts to organization-level defaults. #### Supported Agents | Identifier | Agent | | - | - | | `claude` | Claude Code | | `cursor` | Cursor | | `copilot` | GitHub Copilot | | `continue` | Continue.dev | | `junie` | Junie | | `agents_md` | AGENTS.md | | `gitlab_duo` | GitLab Duo | | `opencode` | OpenCode | | `codex` | Codex | | `kiro` | Kiro | After adding or removing agents, run `packmind install` to deploy or clean up the corresponding agent artifact files in your repository. ## Install Command Download commands, standards, and skills from packages to your local machine. ### List Available Packages ```bash theme={null} packmind packages list ``` ### View Package Details ```bash theme={null} packmind packages show ``` ### 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 ``) * Getting a quick summary of unique packages in your workspace ### Install Packages ```bash theme={null} packmind install [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. **Default skills included** — When you install packages, Packmind's default skills (including the `packmind-update-playbook` skill) are automatically installed alongside your package contents. ### Package Versions Each package listed in `packmind.json` records which version of that package the folder receives. Add the version after the slug to choose it: ```bash theme={null} packmind install @my-space/ops:0.1.0 ``` | What you type | What you get | What `packmind.json` records | | - | - | - | | `@my-space/ops` | The latest release | that release, for example `0.1.0` | | `@my-space/ops:0.1.0` | Exactly that release | `0.1.0` | | `@my-space/ops:*` | The package as it stands, including changes made since the last release | `*` | A package pinned to a version stays on it. Cutting a new release in Packmind does not move a folder that pinned an older one, and neither does running `packmind install` again — your playbook only changes when you decide it does. Asking for a version that was never released stops the install and lists the versions that do exist, newest first. A package that has never been released installs as it stands, recorded as `*`. Each `packmind.json` carries its own versions, so two folders in the same repository can sit on two different releases of the same package. ### Check Upgrades Before Installing See what `packmind install --upgrade` would change before running it: ```bash theme={null} packmind install --check-upgrades ``` **Example output:** ``` @my-space/ops 0.1.0 → 0.2.0 ~ standard Backend conventions v3 → v4 + skill Release notes (new) - command Old deploy (removed) @my-space/frontend * · 2 components to update ~ standard React components v5 → v6 ~ skill Storybook v1 → v2 Run packmind install --upgrade to apply these changes. ``` For each package in `packmind.json`, you see: * **Pinned packages** — the version the package would move from and to (here `0.1.0 → 0.2.0`) * **Packages tracking `*`** — how many of their commands, standards, and skills have changed since your last install * **What changes underneath** — every command, standard, and skill that would be added (`+`), updated (`~`, with its version move), or removed (`-`) A few other changes show up too: * **Coding agents changed in `packmind.json`** — a `Coding agents: claude → claude, cursor` line comes first, and the commands, standards, and skills that would be written to different files are marked `(files change)` * **No packages left in `packmind.json`** — every installed command, standard, and skill is listed as removed, since installing would delete their files When there is nothing to upgrade, the command prints `Already up to date`. If you don't have access to some packages, the command lists them (`Could not check 2 packages you don't have access to: …`) and exits with code `1`, so an incomplete check never passes as up to date. Nothing in your repository changes: `packmind.json`, your lock file, and your installed files stay exactly as they were, and the check is not recorded as an install in Packmind. Run `packmind install --upgrade` when you are ready to apply the changes. The command exits with code `1` when upgrades are available, and code `0` when everything is up to date — handy for flagging an outdated playbook in CI: ```bash theme={null} if ! packmind install --check-upgrades; then echo "Packmind packages have new releases. Run 'packmind install --upgrade'." fi ``` In a monorepo, the check covers the same `packmind.json` files as `packmind install`. Use `--path` to scope it to a specific directory: ```bash theme={null} packmind install --check-upgrades --path apps/api ``` `--check-upgrades` checks the packages already listed in `packmind.json`. It cannot be combined with `--upgrade`, `--status`, or package names. ### Upgrade to the Latest Releases Move every pinned package to its latest release: ```bash theme={null} packmind install --upgrade ``` This rewrites `packmind.json` with the version each package landed on, so you can see exactly what moved in your diff before committing it. To preview what would move first, without changing anything, run `packmind install --check-upgrades` (see [Check Upgrades Before Installing](#check-upgrades-before-installing)). Packages tracking `*` keep tracking it — their line in `packmind.json` is left alone — and their files are refreshed like any install. To move a single package instead, name it with the version you want: ```bash theme={null} packmind install @my-space/ops:0.2.0 ``` ### 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, and under `packages` the version of each package the folder receives: ```json theme={null} { "packages": { "@my-space/ops": "1.2.3" } } ``` Packmind treats this file as the source of truth for what each target runs. See [Keep the Distribution State in Sync with Your Repository](/governance/distribution#keep-the-distribution-state-in-sync-with-your-repository). ### 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 ``` **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). ### Distribution Recording (Tracked Repository and Branch) When you install packages inside a git repository, Packmind records the deployment as a **distribution** so it shows up in your governance and adoption views. To keep those views meaningful, a distribution is recorded **only when you install on the repository and branch your organization tracks** (see [Git Track](#git-track)). If you install anywhere else, the install still completes locally, but nothing is sent to Packmind and the CLI tells you why: * **The repository is not tracked** — no repository is tracked for this project yet: ``` Distribution not recorded — my-org/my-repo is not tracked in Packmind. Ask an admin to run `packmind git track` to start tracking it. ``` * **You are on a different branch** — the repository is tracked, but on another branch: ``` Distribution not recorded — you're on 'dev', but the tracked branch is 'main'. Switch to 'main' to record this distribution. ``` * **The folder is not a tracked git repository** — you are outside a git repository, there is no git remote, or you are not signed in: ``` This folder is not tracked — distribution not recorded in Packmind. ``` **Anyone can install** — Recording a distribution is not restricted to admins. Only *setting* the tracked repository and branch requires an organization admin (see [Git Track](#git-track)). **Not seeing your activity in Packmind?** — Confirm you are on the tracked repository and branch. An organization admin can set or move the tracked branch with `packmind git track`. If the branch was tracked before and is not anymore, its distributions are still kept — they reappear when tracking moves back. See [Distribution History and the Tracked Branch](/governance/distribution#distribution-history-and-the-tracked-branch). ### Install Globally for Claude Code (`~/.claude`) When you run `packmind install` from inside your `~/.claude` directory, the CLI switches into **home-install mode** — a streamlined flow optimized for sharing Packmind artifacts across every project you open in Claude Code, rather than tying them to a single repository. ```bash theme={null} cd ~/.claude packmind install ``` **Why install here:** * **Global availability across projects** — Skills, rules, and commands land directly under `~/.claude/skills/`, `~/.claude/rules/`, and `~/.claude/commands/`, so Claude Code picks them up in any repository you open, not just one you have initialized with Packmind. * **Single-agent rendering** — Only Claude Code artifacts are generated. Any `agents` entries in `packmind.json` and your organization's render modes are ignored, since `~/.claude` is by definition Claude-specific. * **Zero-prompt setup** — If no `packmind.json` exists in `~/.claude`, the CLI auto-creates one with `{"agents": ["claude"]}` and skips the interactive agent prompt entirely. * **Clean file layout** — The `.claude/` path prefix is stripped from rendered files, so artifacts do not nest under a redundant `~/.claude/.claude/` subfolder. * **No `.packmind/` mirror** — The server-side `.packmind/` directory (whose internal links assume a repository layout) is skipped, keeping your home directory uncluttered. * **No distribution notifications** — Even if `~/.claude` happens to live inside a git repository, the CLI does not notify Packmind that a distribution occurred — these artifacts are personal to your machine, not a team deployment. **When to use this mode** — Reach for `~/.claude` installs when you want a package available to Claude Code everywhere: personal coding preferences, cross-project organizational defaults, or experimental skills you want to try without modifying any repository. Per-repo `packmind install` remains the right choice for project-specific standards that should be shared with teammates and committed to source control. ## Distribution Command ### Distribution Record Tell Packmind what the `packmind-lock.json` files in your working copy say each target runs — useful after editing a lock by hand: ```bash theme={null} packmind distribution record ``` * **From the repository root** — every target in the repository is recorded. * **From a sub-folder** — only the targets at or below that folder are recorded. The lock files are found through Git: folders your `.gitignore` excludes are skipped, and lock files you have not committed yet are included. Only the targets that changed are listed in the output. Run it on the tracked branch (see [Git Track](#git-track)). Your lock edits do not need to be pushed, but a later **Sync from repository** in the app reads the locks on the remote branch and shows that state again — push your changes to keep them. See [Keep the Distribution State in Sync with Your Repository](/governance/distribution#keep-the-distribution-state-in-sync-with-your-repository). #### Troubleshooting * **Problem**: `The current directory is not managed by Packmind: no packmind-lock.json here or below records package versions.` * **Solution**: Run `packmind install` to create the lock files, or move to a folder that contains them. * **Problem**: `Nothing recorded: the tracked branch is 'main', and you are on 'dev'.` * **Solution**: Switch to the tracked branch and run the command again. * **Problem**: `Nothing recorded: the current directory is not in a Git repository.` * **Solution**: Run the command from inside the repository's working copy. * **Problem**: A package is reported as not a package of your organization. * **Solution**: That package is not recorded. Check its slug in the lock file, or remove it with `packmind uninstall`. ## 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 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. **Priority** — When both local `packmind.json` files and deployments exist, the local configuration takes priority. ### 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. **Git Repository Required** — The `--changed-files` and `--changed-lines` flags require your project to be in a Git repository. **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. **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. ## 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-onboard** — A skill for initializing Packmind in projects * **packmind-update-playbook** - A skill to manage your playbook: create skills, commands and standards or update the existing ones. **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. ### 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: - my-custom-skill Name: My Custom Skill URL: https://app.packmind.ai/org/my-org/space/global/skills/my-custom-skill/files Description: Custom skill for my project... ``` ### Add a Skill ```bash theme={null} packmind playbook add packmind playbook submit --no-review ``` **Arguments:** * `` - Path to the skill directory containing skill files **Example:** ```bash theme={null} packmind playbook add ./my-skill packmind playbook submit --no-review ``` Use `--no-review` to trigger a [direct update](/playbook-maintenance/updating-your-playbook#direct-updates). Omit `--no-review` to use the [change proposals](/playbook-maintenance/change-proposals) system and get validation of your changes. 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.ai/org/my-org/space/global/standards/abc123/summary Description: Ensure errors are handled predictably... - typescript-conventions Name: TypeScript Conventions URL: https://app.packmind.ai/org/my-org/space/global/standards/def456/summary Description: TypeScript coding conventions... ``` ### Create a Standard See [create a standard from the CLI](/getting-started/gs-create-standard#create-a-standard-from-the-cli) to discover how you can create standards using the CLI. ## 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.ai/org/my-org/space/global/commands/abc123 - setup-database-migration Name: Setup Database Migration URL: https://app.packmind.ai/org/my-org/space/global/commands/def456 ``` ### Create a Command ```bash theme={null} packmind playbook add path/to-command.md packmind playbook submit ``` The markdown file content will be used as the command's prompt. The name of the command will be deduced from the file path. The command markdown should be located in a directory where commands are available. Such directories include:
  • `.packmind/commands`
  • `.cursor/commands`
  • `.github/prompts`
 ## Spaces Command List the spaces available in your Packmind organization. [Spaces](/concepts/spaces) organize standards, commands, skills, and packages within an organization. ### List Spaces ```bash theme={null} packmind spaces list ``` This command displays all spaces in your Packmind organization, showing: * **Slug** — The space identifier (prefixed with `@`) * **Name** — The display name **Example output:** ``` Available spaces: - @global Name: Global - @security Name: Security ``` ## 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 ``` **Arguments:** * `` - 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 `packages add` command. ### 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](/concepts/spaces), Packmind appends a counter (e.g., `backend-standards-1`) to ensure uniqueness. ### Add Items to a Package ```bash theme={null} packmind packages add --to --standard packmind packages add --to --command packmind packages add --to --skill ``` **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 ``` **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. **One item, one package** — An item belongs to a single package. If the item already belongs to another one, `packages add` changes nothing and prints the `packages move` command that would relocate it: ``` $ packmind packages add --to backend --command create-api-endpoint Command "Create API endpoint" already belongs to package "@my-space/api" Run `packmind packages move --command create-api-endpoint --to @my-space/backend` to move the command. ``` ### Move Items Between Packages ```bash theme={null} packmind packages move --to --standard packmind packages move --to --command packmind packages move --to --skill ``` Adds the item to the target package and removes it from **every** other package it belonged to. An item already in the target package and nowhere else is left untouched. **Options:** | Flag | Description | | - | - | | `--to` | Target package slug (required) | | `--standard` | Slug of the standard to move into the package | | `--command` | Slug of the command to move into the package | | `--skill` | Slug of the skill to move into the package | **Example:** ``` $ packmind packages move --command create-api-endpoint --to @my-space/backend Command "Create API endpoint" has been added to package "@my-space/backend" It has been removed from "@my-space/api" ``` When the item came from several packages, they are listed: ``` $ packmind packages move --command create-api-endpoint --to @my-space/backend Command "Create API endpoint" has been added to package "@my-space/backend" It has been removed from the following packages: - @my-space/api - @my-space/legacy ``` ### Remove Items From a Package ```bash theme={null} packmind packages remove --from --standard packmind packages remove --from --command packmind packages remove --from --skill ``` **Options:** | Flag | Description | | - | - | | `--from` | Slug of the package to remove from (required) | | `--standard` | Slug of the standard to remove from the package | | `--command` | Slug of the command to remove from the package | | `--skill` | Slug of the skill to remove from the package | **Example:** ``` $ packmind packages remove --command create-api-endpoint --from @my-space/backend Command "Create API endpoint" has been removed from package "@my-space/backend" It does not belong to any package anymore ``` An item that belongs to no package is no longer installed or distributed anywhere. The command always states what the item still belongs to, so you can tell the two outcomes apart. ## Plugins Command Publish a Packmind package as a [Claude Code plugin](https://docs.claude.com/en/docs/claude-code/plugins) or a GitHub Copilot plugin, so its commands and skills can be installed directly into your coding agent — either from your own [marketplace](https://docs.claude.com/en/docs/claude-code/plugin-marketplaces) or, for Claude Code, as a standalone plugin repository. A rendered plugin contains the package's commands and skills — as slash commands and skills for Claude Code, as prompt files and skills for GitHub Copilot. Standards are not rendered because plugins do not support them, for either vendor — when a package contains standards, the CLI reports how many were skipped. **GitHub Copilot marketplaces are supported too** — a repository containing `.github/plugin/marketplace.json` instead of `.claude-plugin/marketplace.json` is a GitHub Copilot marketplace, and `plugins render` writes a Copilot-formatted plugin into it instead of a Claude Code one, in the same `plugins//` layout. A repository can only be one or the other, never both, the same way [marketplaces linked from the web app](/governance/marketplaces) work. ### Choose Your Workspace Mode The `plugins` commands detect what kind of workspace you are in by looking for a marketplace or plugin manifest: | File present | Mode | Use case | | - | - | - | | `.claude-plugin/marketplace.json` | **Marketplace (Claude Code)** | A repository that hosts multiple plugins, each under `plugins//` | | `.github/plugin/marketplace.json` | **Marketplace (GitHub Copilot)** | Same as above, rendered as GitHub Copilot plugins instead | | `.claude-plugin/plugin.json` | **Standalone** | A repository that contains a single plugin at its root (Claude Code only) | | None of the above | *Not supported* | The CLI exits with an error asking you to create one of the manifests first | **Setting up a marketplace** — Create a `.claude-plugin/marketplace.json` file at the root of a Git repository with the shape `{ "name": "", "owner": { "name": "" }, "plugins": [] }`. The CLI fills in the `plugins` array for you as you render packages. See Anthropic's [marketplace documentation](https://docs.claude.com/en/docs/claude-code/plugin-marketplaces) for the full schema. **Setting up a standalone plugin** — Create a `.claude-plugin/plugin.json` file at the root of a Git repository with at least `{ "name": "" }`. The plugin name must match the package slug you intend to render. ### Plugins Render Render a Packmind package as a Claude Code or GitHub Copilot plugin in the current workspace. ```bash theme={null} packmind plugins render ``` **Arguments:** * `` — Slug of the package to render (for example, `security` or `@my-space/security`) #### Marketplace Workflow Run the command from the root of your marketplace repository (the directory that contains `.claude-plugin/marketplace.json`): ```bash theme={null} packmind plugins render security ``` The CLI will: 1. Download the package's commands and skills from your Packmind organization 2. Write them under `plugins/security/` (commands in `plugins/security/commands/`, skills in `plugins/security/skills/`), along with the plugin manifest at `plugins/security/.claude-plugin/plugin.json` 3. Add or update the plugin entry inside `.claude-plugin/marketplace.json`, pointing `source` to `./plugins/security` **GitHub Copilot marketplaces** — The CLI picks the plugin format from the descriptor it finds. A repository holding `.github/plugin/marketplace.json` instead is rendered in the Copilot format: commands land in `plugins/security/.github/prompts/` as `.prompt.md` files, and the manifest is written at `plugins/security/.github/plugin/plugin.json` — the path Copilot probes — instead of `plugins/security/.claude-plugin/plugin.json`. Skills are rendered under `plugins/security/skills/` for both vendors. **Example output:** ``` Rendered 12 files into ./plugins/security/ Skipped 3 standards (not supported in plugins). Updated .claude-plugin/marketplace.json ``` When the same plugin is rendered again, the CLI asks for confirmation before overwriting: ``` Plugin "security" already exists at "./plugins/security". Overwrite? [y/N] ``` #### Standalone Workflow Run the command from the root of your standalone plugin repository (the directory that contains `.claude-plugin/plugin.json`): ```bash theme={null} packmind plugins render security ``` The CLI will: 1. Verify that the package slug matches the `name` field declared in `plugin.json` 2. Download the package's commands and skills 3. Write them directly at the repository root (`commands/` and `skills/`) Because a standalone repository already represents the plugin, the CLI always asks for confirmation before overwriting existing files: ``` Plugin "security" already exists in this workspace. Overwrite? [y/N] ``` **Git remote detected automatically** — When the workspace is a Git repository with a remote, the CLI captures the remote URL and current branch and sends them to Packmind so the distribution is tracked alongside your other deployments. ### Plugins Delete Remove a rendered plugin from the current workspace and notify Packmind that the distribution has been deleted. Like `render`, it works in whichever workspace mode it detects — a Claude Code or a GitHub Copilot marketplace, or a standalone Claude Code plugin. ```bash theme={null} packmind plugins delete ``` **Arguments:** * `` — Slug of the plugin to delete (matches the package slug used during `render`) #### Marketplace Workflow Run the command from the root of your marketplace repository: ```bash theme={null} packmind plugins delete security ``` The CLI will: 1. Locate the plugin entry in the marketplace descriptor it found — `.claude-plugin/marketplace.json` for Claude Code, `.github/plugin/marketplace.json` for GitHub Copilot 2. Ask for confirmation: ``` Remove ./plugins/security and update marketplace.json for plugin "security"? [y/N] ``` 3. Delete the plugin directory (for example, `./plugins/security`) and remove its entry from that descriptor If the plugin is not declared in the descriptor, the command exits without changes: ``` Plugin "security" is not declared in marketplace.json. Nothing to delete. ``` **Both vendors are covered** — Deleting removes the whole `plugins//` directory, so a Copilot plugin's `.github/prompts/`, `skills/` and `.github/plugin/plugin.json` go with it, exactly as a Claude Code plugin's `commands/`, `skills/` and `.claude-plugin/plugin.json` do. #### Standalone Workflow Run the command from the root of your standalone plugin repository: ```bash theme={null} packmind plugins delete security ``` After confirmation, the CLI removes the rendered `commands/` and `skills/` directories. The `.claude-plugin/plugin.json` manifest is left untouched so you can re-render the plugin later. Standalone mode is Claude Code only — there is no GitHub Copilot equivalent of a single-plugin-at-the-root repository, so Copilot plugins are always managed through the marketplace workflow above. ### Troubleshooting * **Problem**: `No .claude-plugin/marketplace.json, .github/plugin/marketplace.json, or .claude-plugin/plugin.json found in this directory.` * **Solution**: Run the command from the root of a workspace that contains one of these manifests. Create the appropriate manifest first if the workspace is brand new. * **Problem**: ` is not valid JSON. Fix the file and try again.` * **Solution**: The marketplace manifest Packmind found has a syntax error. Fix the JSON in that file and run the command again. * **Problem**: `The plugin '' is not handled in this repo.` (standalone mode) * **Solution**: The package slug you passed does not match the `name` declared in `.claude-plugin/plugin.json`. Update the manifest or pass the matching slug. * **Problem**: `Plugin "" has a remote source. Run this command in the workspace of the remote plugin.` * **Solution**: The marketplace entry points to a remote source (for example, a GitHub repository) rather than a local folder. Switch to the workspace that owns the remote plugin and run the command there. * **Problem**: Some content from the package is missing in the rendered plugin. * **Solution**: Standards are intentionally skipped because plugins do not support them, for either vendor. Check the `Skipped N standards` line in the command output to see how many were excluded. ## Playbook Command Manage local artifact changes and propose them to your team using a git-like staging workflow. The `playbook` command groups six subcommands: `diff`, `status`, `add`, `rm`, `unstage`, and `submit`. ### View Differences ```bash theme={null} packmind playbook diff ``` Compares your local artifact files (standards, commands, skills) against the versions published in Packmind. 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 **Options:** | Flag | Short | Description | | - | - | - | | `--include-submitted` | | Include already-submitted changes in the output | | `--path ` | `-p` | Limit analysis to a specific path | ### Check Status ```bash theme={null} packmind playbook status ``` Shows staged changes ready for submission and untracked local modifications. **Example output:** ``` Changes to be submitted: - Standard "Error Handling" (updated) .claude/rules/error-handling.md Changes not tracked: - Command "Deploy" (modified) .claude/commands/deploy.md Use `packmind playbook add ` to track them ``` ### Stage Changes ```bash theme={null} packmind playbook add ``` Stages a local artifact change for submission. The change type (created or updated) is detected automatically by comparing with the deployed version. ### Stage Removal ```bash theme={null} packmind playbook rm ``` Stages an artifact for removal from the playbook. The artifact must have been distributed by Packmind. Alias: `remove`. ### Unstage Changes ```bash theme={null} packmind playbook unstage ``` Removes a previously staged change from the playbook without submitting it. ### Submit Proposals ```bash theme={null} packmind playbook submit -m "Improve error handling rules for better observability" ``` Submits all staged changes as change proposals for team review in the Packmind web app. | Flag | Short | Description | | - | - | - | | `--message ` | `-m` | Message describing the intent behind the changes (max 1024 chars) | If you omit `-m`, Packmind opens your default editor so you can write the message interactively. ### 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. **Requires a git repository** — The `playbook` 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 `playbook`. ## 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) ``` **Permission error on Linux/macOS** — If you see a permission denied error, run the command with `sudo`: ```bash theme={null} sudo packmind update ``` ### 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 ``` 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. ## 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 # Import existing content from Confluence, Notion and more Source: https://docs.packmind.com/tools/import-from-knowledge-base ## Why import from your knowledge base? Teams often have coding guidelines, conventions, and processes documented in wikis and knowledge bases. With MCP, your AI coding assistant can read directly from these sources and create Packmind artifacts — Standards, Commands, and Skills — without copy-pasting or rewriting content manually. ## What is MCP? MCP (Model Context Protocol) is an open protocol that lets AI agents connect to external data sources. Packmind leverages MCP to import content from any compatible knowledge base. ## Supported knowledge bases Any tool that exposes an MCP server works with this workflow. Here are two popular options: * **Confluence** — Follow the [Atlassian MCP server setup guide](https://support.atlassian.com/atlassian-rovo-mcp-server/docs/getting-started-with-the-atlassian-remote-mcp-server/) to connect your Confluence workspace. * **Notion** — Follow the [Notion MCP setup guide](https://developers.notion.com/guides/mcp/get-started-with-mcp.md) to connect your Notion workspace. Once MCP is configured in your AI coding assistant, Packmind can access your knowledge base pages directly. ## Demo Here is an example of importing coding guidelines from Confluence into Packmind: