When you run hopsule decision create from your terminal, something powerful happens. You aren't just creating a record; you are initializing an enforceable constraint that will govern the future of your engineering organization. As engineers, we live in the terminal. It is the environment where we compile code, manage infrastructure, and orchestrate deployments. It only makes sense that the governance of our technical decisions—the very soul of our engineering judgment—should reside there as well. At Hopsule, we built the Hopsule CLI to ensure that the context of your decisions is never more than a few keystrokes away.
In this guide, I want to walk you through the technical depth of the Hopsule CLI. We will explore how it facilitates the decision lifecycle, how it integrates with the Hopsule Dashboard and Hopsule for VS Code, and how you can use it to enforce organizational memory within your CI/CD pipelines. This isn't just about a tool; it's about a workflow that prioritizes remembrance over control and authority over ambiguity.
The Philosophy of Terminal-Based Governance
Engineering organizations often suffer from a phenomenon I call "context erosion." A decision is made in a meeting or a chat thread, implemented in code, and then promptly forgotten. Six months later, a new engineer asks why a specific architectural pattern was used, and the only answer is a shrug. Hopsule CLI exists to stop this erosion. By bringing decision management into the terminal, we treat engineering decisions with the same rigor as source code. We version them, we track their status, and we make them searchable.
The CLI is designed to be the primary interface for the "Decision-First" philosophy. Unlike a standard web interface, the terminal allows for rapid iteration and integration into existing developer workflows. When you are in the middle of a refactor and realize you need to deviate from an established pattern, you shouldn't have to switch contexts to a browser. You should be able to query the Hopsule CLI, understand the memory behind the original decision, and draft a new decision or a memory entry immediately. This is what we mean by context-aware engineering.
Furthermore, the CLI acts as the bridge between the human developer and the Hopsule MCP. While AI agents can read your decisions via the MCP server, the CLI is where the human authority is asserted. It is the tool that allows you to move a decision from Pending to Accepted, signaling to both your human teammates and your AI assistants that a new standard has been set. This level of governance is what separates a high-functioning engineering team from one that is merely "productive" in the short term.
Installation and Authentication: Setting the Foundation
Getting started with the Hopsule CLI is a straightforward process, but it requires an understanding of how we handle identity and authority. Because Hopsule is a governance system, security is not an afterthought—it is the baseline. Every interaction with the Hopsule API via the CLI is protected by end-to-end encryption and strict authentication protocols.
Environment Configuration
Once the binary is installed, the first step is authentication. We use a token-based system that links your local environment to your Hopsule account. Running hopsule auth login will initiate a secure handshake. This process ensures that your local machine is recognized as a trusted node within your organization's memory system. For enterprise teams using Hopsule Enterprise (Self-Hosted), the CLI can be configured to point to your internal infrastructure, ensuring that your data never leaves your environment.
The CLI also supports multi-organization and multi-project configurations. If you are a senior developer overseeing multiple product lines, you can easily switch contexts using the hopsule config command. This allows you to manage different sets of Context Packs (Capsules) without overlapping the governance rules of distinct teams. The configuration is stored locally in an encrypted format, maintaining the integrity of your session across different terminal instances.
The Decision Lifecycle: From Draft to Deprecated
The core entity of Hopsule is the Decision. A decision is not a static note; it is a live commitment with a defined lifecycle. The Hopsule CLI provides a suite of commands to manage this lifecycle with precision. When you initiate a decision, you are starting a process of organizational remembrance.
Creating and Drafting Decisions
To start a new decision, you use hopsule decision create. This opens your system's default editor (or an interactive prompt) where you define the title, the scope, and the initial reasoning. At this stage, the decision is in a Draft state. It is visible to you but has not yet been broadcast as an enforceable constraint. This is the time for refinement. You can link existing Memories to the decision to provide historical context, explaining *why* this decision is being proposed now.
For example, if you are proposing a move to a specific concurrency model, your draft might look like this:
Once the draft is ready, you move it to Pending. This signals to the rest of the team—and to Hopper, our AI assistant—that a decision is up for review. During the Pending phase, team members can attach additional memories or comments via the Hopsule Dashboard or the CLI, creating a rich audit trail of the reasoning process.
Acceptance and Enforcement
When the team reaches a consensus, an authorized member (typically a lead or architect) will run hopsule decision accept [ID]. This is a critical moment. The decision is now moved to the Accepted state. It is no longer just a proposal; it is an active constraint. Immediately, this decision becomes visible in Hopsule for VS Code. Any developer working on the project will see warnings if their code contradicts this accepted decision. This is how we achieve enforcement through remembrance. We aren't controlling the developer; we are reminding them of the collective judgment they agreed to follow.
Eventually, decisions become obsolete. Technology shifts, and what was once a best practice becomes a legacy burden. The hopsule decision deprecate [ID] command allows you to gracefully retire a decision. It doesn't disappear—Hopsule never forgets—but it is marked as Deprecated, and a new decision is typically linked as its successor. This maintains the lineage of your engineering governance, allowing future engineers to trace the evolution of your system through the Knowledge Graph.
The Interactive TUI and the Knowledge Graph
While the CLI is powerful for individual commands, we realized that engineers often need a more holistic view of their project's memory. This led us to develop the Hopsule TUI (Terminal User Interface). By running hopsule dashboard (the terminal version), you enter an interactive ASCII-based environment that mirrors the core functionality of the Hopsule Dashboard.
The TUI provides a real-time activity feed of recent decisions and memories. You can navigate through different Context Packs, view the status of pending decisions, and even visualize the Knowledge Graph (Brain) using specialized terminal layouts. The Knowledge Graph is particularly important because it shows the relationships between decisions. You can see how a decision made in the "Infrastructure" capsule might be impacting decisions in the "API Design" capsule. This visualization helps identify potential conflicts before they become technical debt.
Within the TUI, you can also interact with Hopper. If you are looking at a complex decision and need a summary of the underlying memories, you can ask Hopper to explain the reasoning. Hopper uses RAG (Retrieval-Augmented Generation) to pull from your team's specific history, ensuring that the advice it gives is grounded in your organization's actual judgment, not just general internet knowledge. Remember, Hopper is advisory; it can suggest improvements to a decision's wording or detect a conflict with an existing Accepted decision, but it will never change a state on its own.
Context Packs (Capsules): Portability of Judgment
One of the most innovative features of Hopsule is the concept of Context Packs, or Capsules. A Capsule is a portable bundle of decisions and memories. In the CLI, you manage these using the hopsule capsule command set. Capsules are designed to survive time, people, and system changes. They are the units of memory that you can share across projects or even across different organizations.
Imagine you have developed a set of "Security Best Practices" for your microservices. Instead of documenting these in a static file that will inevitably be ignored, you create a Security Capsule. This capsule contains all the accepted decisions regarding encryption, authentication, and data handling, along with the memories that explain why those specific standards were chosen. Using the CLI, you can "push" this capsule to a central registry and "pull" it into any new project.
Once pulled, the decisions within that capsule are immediately active for that project. Hopsule for VS Code will start enforcing those security standards, and the Hopsule CLI will include them in its conflict detection checks. This portability ensures that your organization's judgment is consistent across its entire technical footprint. The lifecycle of a capsule—Draft, Active, Frozen, Historical—allows you to manage the versioning of these judgment bundles with the same care you manage your software releases.
Memories: The Append-Only Ledger of Reasoning
If decisions are the "what," memories are the "why." In Hopsule, memories are persistent, append-only context entries. They are never deleted and never overwritten. This is a fundamental technical choice we made to ensure full traceability. The Hopsule CLI makes it incredibly easy to capture these memories as they happen.
When you are debugging a particularly nasty production issue, you might discover that a specific architectural choice is causing a bottleneck. You can immediately run hopsule memory create to capture this insight. You aren't making a new decision yet; you are just recording a piece of context that will inform future decisions. You can link this memory to an existing decision to provide a "lesson learned" or a "reason for future change."
The command hopsule memory list --decision [ID] allows you to see the entire history of reasoning behind a specific commitment. This is invaluable during architectural reviews or onboarding. Instead of digging through old Slack messages or Jira tickets, a developer can see a clean, chronological ledger of every thought, experiment, and failure that led to the current state of the system. This is what we mean by organizational judgment. It is the sum of all the memories that have been preserved over time.
CI/CD Integration and Automated Enforcement
As a CTO, I am often asked how we ensure that decisions are actually followed. The answer lies in the Hopsule CLI's ability to integrate into CI/CD pipelines. Because the CLI can return structured data and exit codes based on decision status, it can be used as a gatekeeper for your deployment process.
You can configure your CI pipeline to run a hopsule check command. This command scans the project for any "overrides" that have been flagged by Hopsule for VS Code. When a developer intentionally contradicts an Accepted decision in their IDE, they must provide an acknowledgment. The CLI can detect these acknowledgments and, depending on your organization's policy, either trigger a warning or fail the build until a senior engineer reviews the deviation.
This creates a powerful feedback loop. It ensures that the "Enforcement is remembrance" philosophy is backed by technical reality. If a decision is important enough to be Accepted, it is important enough to be checked before code hits production. This level of governance is achieved without the heavy-handedness of traditional policy engines, because the "rules" are the very decisions the team itself made and recorded in Hopsule.
Hopper: AI Advisory in the Terminal
While the CLI is a tool for human authority, it is enhanced by Hopper, our AI assistant. Hopper is integrated directly into the CLI to provide real-time advisory services. It is important to reiterate: Hopper never makes decisions. It assists in the preservation and drafting of context.
One of the most useful Hopper commands is hopsule hopper suggest. If you have a rough idea for a new architectural direction, you can pipe your notes into Hopper, and it will draft a formal decision for you, complete with tags and links to relevant historical memories. It might say, "I see you are proposing a GraphQL migration. Did you know there is an Accepted decision from last year in the 'Mobile' capsule that warns against over-fetching in low-bandwidth environments? I've linked that memory to your draft for your review."
This context-aware assistance is only possible because Hopsule treats decisions and memories as first-class entities. Hopper isn't just guessing; it is querying your organization's Knowledge Graph. It acts as a digital librarian, ensuring that when you are about to make a new decision, you are fully aware of the judgment that has come before. This reduces the cognitive load on senior developers and helps prevent the repetition of past mistakes.
The Hopsule API and Custom Integrations
For organizations with complex workflows, the Hopsule CLI is just the beginning. The Hopsule API provides a RESTful interface for building custom integrations. Whether you want to trigger a decision review based on a GitHub PR or sync memories with an internal incident management system, the API gives you programmatic access to the entire memory layer.
We also provide the Hopsule MCP (Model Context Protocol) server. This allows you to connect any MCP-compatible AI agent—like those found in Cursor or Claude—directly to your Hopsule decisions and memories. This means your AI coding assistants become "context-aware" automatically. They will stop suggesting patterns that contradict your Accepted decisions because they can "read" the governance layer of your organization. The CLI serves as the management tool for these connections, allowing you to monitor API usage and manage access tokens securely.
Conclusion: The Future of Engineering Memory
The Hopsule CLI is more than just a utility; it is a manifestation of our belief that engineering organizations should be built on a foundation of preserved judgment. By bringing decision management, memory preservation, and enforcement into the terminal, we are giving engineering teams the tools they need to maintain context across time and scale. We are moving away from the era of "forgotten meetings" and toward an era of "organizational remembrance."
As we continue to develop Hopsule, the CLI will remain at the center of our ecosystem. We are working on deeper integrations with the Knowledge Graph, more advanced TUI visualizations, and even tighter loops between the terminal and Hopsule for VS Code. Our goal is to make the act of capturing a decision as natural as committing code. When your team's most important decisions are enforceable, portable, and always accessible, you don't just build better software—you build a better organization.
If you haven't yet integrated Hopsule into your workflow, I encourage you to start with the CLI. Run hopsule decision create, capture your first memory, and feel the difference that a decision-first architecture makes. Your future self—and your future teammates—will thank you for it. Organizations forget. Hopsule remembers.
SHARE ON SOCIAL MEDIA
