Hopsule CLI: Command Reference

Introduction to the Hopsule CLI

The Hopsule CLI is the primary interface for engineering teams to interact with their decision and memory layer directly from their development environment. It is designed to bridge the gap between high-level organizational judgment and the daily workflow of developers. By bringing governance into the terminal, Hopsule ensures that context preservation is a natural part of the software development lifecycle rather than an external administrative task. The CLI provides a robust set of tools for managing the entire lifecycle of Decisions, Memories, and Context Packs, allowing teams to maintain a high-fidelity record of their reasoning without leaving their shells.

As a core component of the Hopsule ecosystem, the CLI works in tandem with the Hopsule Dashboard and Hopsule for VS Code. While the dashboard provides a high-level visualization of your Knowledge Graph, the CLI is optimized for speed, automation, and integration into CI/CD pipelines. It treats Decisions as first-class, enforceable entities, enabling developers to propose, review, and commit to architectural or procedural constraints with the same rigor they apply to source code. The CLI adheres to the philosophy that enforcement is remembrance, providing the necessary context to understand why certain paths were chosen and ensuring those choices remain visible over time.

Authentication and Identity

Before interacting with your organization's memory system, you must establish a secure session. The auth command group manages your identity and access tokens, ensuring that every action taken is attributed to a specific authorized member of the team. Hopsule utilizes industry-standard encryption for all data in transit, and the CLI manages these secure connections transparently.

hopsule auth login

The login command initiates the authentication process. It opens a secure browser window where you can provide your credentials. Once authenticated, the Hopsule Dashboard issues a unique session token that the CLI stores locally in a secure, encrypted format. This command is the first step for any new environment, whether it is a local workstation or a shared development server.

Note: If you are working in a headless environment where a browser is not available, you should use the --token flag or the HOPSULE_TOKEN environment variable to authenticate programmatically.

hopsule auth status

To verify your current authentication state and view which organization and project you are currently targeting, use the status command. This provides a summary of your identity, the expiration of your current session, and the connectivity status to the Hopsule API. It is a useful diagnostic tool to ensure your environment is correctly configured before performing governance actions.

hopsule auth logout

The logout command securely terminates your local session and invalidates the local token. This is an essential command for maintaining security hygiene, especially when working on shared hardware or temporary environments. Once executed, the CLI will require a fresh login before any further commands can be issued.

Project and Organization Management

Hopsule is built to support multi-org and multi-project environments. Engineering leaders often manage several distinct products or microservices, each requiring its own set of Decisions and Memories. The project command group allows you to navigate these organizational structures and ensure your context is being preserved in the correct location.

hopsule project list

This command displays all projects you have access to across all organizations. It provides a high-level view of the project names, their unique identifiers, and the number of Accepted Decisions currently enforced within each project. This is the primary way to discover where context is being managed across the enterprise.

hopsule project select

To set a specific project as your active context, use the select command. This updates your local configuration so that subsequent commands—such as creating a Decision or listing Memories—automatically target the chosen project. This prevents the need to pass a --project flag with every single command.

hopsule project info

The info command provides a detailed summary of the active project. This includes the project's description, the primary stakeholders, and a breakdown of the Context Packs currently active. It also shows the health of the project's Knowledge Graph, highlighting how many Memories are linked to Decisions.

Decision Management

Decisions are the heart of Hopsule. They represent explicit commitments the team agrees to follow. Unlike a simple text entry, a Decision in Hopsule has a formal lifecycle: Draft, Pending, Accepted, and Deprecated. The CLI provides the tools to move through this lifecycle with precision.

hopsule decision create

Creating a Decision is the act of formalizing a choice. When you run this command without flags, it launches an interactive TUI (Terminal User Interface) that guides you through providing a title, a detailed description, and the reasoning behind the choice. You can also assign tags to categorize the decision within the Brain visualization.

Tip: You can use Hopper, the built-in AI assistant, to help draft these decisions by providing a natural language prompt. Hopper will suggest improvements and detect potential conflicts with existing Decisions, though the final commitment always remains with the human operator.

hopsule decision list

The list command allows you to browse the repository of organizational judgment. It supports powerful filtering options to help you find specific constraints. You can filter by the current state (e.g., only show Accepted decisions), by specific tags, or by the author of the decision. This command is essential for developers who need to quickly understand the constraints of a new project.

hopsule decision view

To read the full context of a specific decision, use the view command followed by the decision's slug or ID. This displays the full description, the reasoning (linked Memories), the current version history, and any Context Packs it belongs to. This is where the preservation aspect of Hopsule becomes visible, as you can see the entire history of why a decision was made.

hopsule decision accept

Accepting a decision is a significant governance event. It transitions a Decision from Pending to Accepted, at which point it becomes an enforceable constraint. Once accepted, Hopsule for VS Code will begin monitoring the codebase for contradictions, and Hopsule MCP will inform AI agents of this new rule. This command requires the --reason flag to document why the team has reached a consensus.

hopsule decision deprecate

Organizations evolve, and old decisions eventually become obsolete. The deprecate command allows you to retire a decision without deleting it. This preserves the historical context—showing that the decision *once* existed and why it was eventually replaced. This is a key part of organizational memory, preventing future teams from repeating the same mistakes or questioning why a previous standard was abandoned.

Memory Management

Memories are persistent, append-only context entries that explain the *why* behind your decisions. While a Decision is a rule, a Memory is the history, the lessons learned, and the reasoning that led to that rule. In Hopsule, Memories are never deleted and never overwritten, ensuring a permanent audit trail of engineering judgment.

hopsule memory create

Use this command to record an observation, a post-mortem result, or a piece of architectural reasoning. Memories are most powerful when linked to a Decision, as they provide the evidentiary support for that decision's existence. You can link a memory during creation using the --decision flag.

Important: Memories are append-only. Once a memory is committed to the system, it cannot be edited or removed. This ensures the integrity of your organization's history and prevents the rewriting of past events.

hopsule memory list

This command retrieves a chronological feed of memories for the current project. It is particularly useful for new team members who want to "replay" the history of the project to understand how it arrived at its current state. You can filter the list by date range or by the Decision they are associated with.

Context Packs and Capsules

Context Packs (also known as Capsules) are portable bundles of Decisions and Memories. They are designed to survive time, people, and system changes. By grouping related decisions into a Capsule, you can easily share a specific set of governance rules across different projects or teams.

hopsule capsule create

A Capsule is created by selecting a set of existing Decisions and Memories and giving them a collective identity. This is useful for creating "Standard Operating Procedures" or "Security Baselines" that apply to multiple repositories. The create command allows you to define the scope and initial contents of the pack.

hopsule capsule list

This command lists all Context Packs available to your organization. It shows their current lifecycle state: Draft, Active, Frozen, or Historical. A Frozen capsule is one that has been locked for compliance or archival purposes, ensuring its contents can never be altered again.

hopsule capsule view

The view command provides a detailed look at the contents of a Context Pack. It lists every Decision included in the bundle and provides links to the Knowledge Graph to see how these decisions relate to one another. This is the primary way to audit the contents of a governance bundle before applying it to a new project.

System Status and Search

To maintain a high-level view of your organization's memory health, the Hopsule CLI provides diagnostic and discovery tools. These commands help you visualize the state of your Knowledge Graph and find information across the entire system.

hopsule status

The status command provides a project-level overview. It displays counts of decisions by state, a summary of recent activity (who added what context and when), and the overall health of the project's documentation. It is an essential command for engineering leads to monitor the pulse of their team's governance activities.

The output includes a breakdown of:

• Active Decisions: The number of constraints currently being enforced.

• Pending Proposals: Decisions currently awaiting review or consensus.

• Memory Velocity: The rate at which new context entries are being added.

• Knowledge Gaps: Areas where decisions lack supporting memories or reasoning.

hopsule search

Hopsule's search command is more than a simple grep. It queries your organization's Knowledge Graph to find relevant Decisions, Memories, and Context Packs based on your query. It uses the same RAG-powered engine that drives Hopper, ensuring that results are contextually relevant to your engineering domain.

Data Portability and Export

Hopsule believes in full data sovereignty. Your organizational judgment should never be locked into a single platform. The export command allows you to take your Decisions and Memories with you in various formats.

hopsule export

This command generates a complete dump of your project's context. You can choose between json for programmatic use, or markdown for generating static documentation sites or internal reports. This ensures that even if you choose to move away from Hopsule, your team's history and reasoning remain accessible and readable.

Global Flags and Configuration

The Hopsule CLI supports a set of global flags that can be used with almost any command to modify its behavior or output format. These are particularly useful when using the CLI in scripts or automation pipelines.

Environment Variables

In addition to flags, the CLI can be configured using environment variables. This is the preferred method for configuring Hopsule in CI/CD environments like GitHub Actions, GitLab CI, or Jenkins.

• HOPSULE_TOKEN: Your personal or service account access token.

• HOPSULE_PROJECT: The default project ID to use for all commands.

• HOPSULE_API_URL: The endpoint for the Hopsule API (used primarily for Hopsule Enterprise self-hosted deployments).

Error Handling and Exit Codes

The Hopsule CLI is designed to be a reliable component of your toolchain. It uses standard POSIX exit codes to indicate the success or failure of a command. This allows you to build robust scripts that react correctly to different scenarios, such as authentication failures or conflicting decisions.

Important: When a command fails with a Conflict (Code 4), it means the Hopsule API has detected a logical contradiction in your Knowledge Graph. You should use hopsule decision view on the conflicting decision to understand the existing constraint before attempting to override it.

Best Practices for CLI Governance

To get the most out of the Hopsule CLI, engineering teams should integrate it into their daily habits. Governance is most effective when it is continuous rather than a quarterly event. Here are several recommended practices for using the CLI effectively:

1. Commit Decisions with Code: When you submit a Pull Request that introduces a new architectural pattern, use hopsule decision create at the same time. Link the decision to the PR so the reasoning is preserved alongside the implementation.

2. Use Memories for Post-Mortems: After resolving a production incident, use hopsule memory create to record the root cause and the lessons learned. Link these memories to any Decisions that were made as a result of the incident.

3. Automate with CI: Use hopsule status in your CI pipeline to fail builds if there are Pending Decisions that have not been addressed, or if the project's Knowledge Graph health falls below a certain threshold.

4. Leverage the TUI: For complex tasks like creating a detailed decision, the interactive TUI provides a much better experience than passing dozens of flags. Simply run hopsule decision create and follow the prompts.

By following these practices, your team ensures that organizational judgment is never lost and that the authority behind your engineering choices is always clear. The Hopsule CLI is your partner in this journey, providing the tools to make remembrance a fundamental part of your engineering excellence.