Managing Decisions From Your Terminal

Managing Decisions From Your Terminal

The Hopsule CLI is the primary interface for developers who prioritize velocity and precision in their decision-making workflows. By integrating decision governance directly into the terminal, engineering teams can preserve organizational judgment and enforce architectural constraints without ever leaving their development environment. This guide provides an exhaustive overview of how to leverage the Hopsule CLI to maintain a robust, context-aware memory system for your team.

Prerequisites

Before you begin managing decisions from your terminal, ensure you have completed the following steps to establish a secure connection between your local environment and the Hopsule infrastructure:

• Active Hopsule Account: You must have a valid account and be a member of an organization within the Hopsule Dashboard.

• Personal Access Token: Navigate to the Settings section of the Hopsule Dashboard and generate a secure API token. This token is required for the Hopsule CLI to authenticate your identity and verify your permissions.

• CLI Installation: Ensure the Hopsule CLI is installed on your machine. You can verify the installation by running hopsule --version in your terminal.

• Project Initialization: Your local project directory should be initialized with a Hopsule configuration file to link it to the correct organization and project context.

Authenticating the Hopsule CLI

To begin using the Hopsule CLI, you must first authenticate your local session. This process ensures that every decision you create or modify is attributed to your identity, maintaining a clear audit trail and preserving the authority of the decision lifecycle.

1. Open your terminal and execute the login command.

2. When prompted, paste the Personal Access Token you generated from the Settings tab of the Hopsule Dashboard.

3. The Hopsule CLI will validate the token against the Hopsule API and establish an encrypted session.

4. Upon successful authentication, the CLI will display a confirmation message along with your current organization and project context.

Once authenticated, the Hopsule CLI remains active until the token is revoked or expires. You can check your current authentication status at any time by using the hopsule status command, which provides a summary of your active session and organizational context.

Creating and Drafting Decisions

Decisions are the first-class entities of the Hopsule ecosystem. They represent the explicit commitments your team makes regarding architecture, patterns, and workflows. In the terminal, you can initiate these decisions as drafts, allowing for refinement before they become enforceable constraints.

1. Initiate a New Decision: Run the command to create a new decision. You will be prompted to provide a concise, descriptive title that captures the essence of the commitment.

2. Define the Decision Context: Provide a detailed description of the decision. This should outline the "what" of the decision—the specific rule or constraint being proposed.

3. Leverage Hopper for Drafting: If you are unsure of the phrasing or need to check for existing contradictions, you can invoke Hopper, the built-in AI assistant. Hopper can analyze your existing decisions and memories to suggest improvements or identify potential conflicts with historical context.

4. Attach Initial Memories: Every decision should be accompanied by a memory that explains the "why." Use the terminal interface to append the reasoning, trade-offs considered, and the specific problem this decision aims to solve.

5. Save as Draft: By default, new decisions are created in the Draft state. This allows your team to review the proposal in the Hopsule Dashboard before it is promoted to a pending or accepted status.

Listing and Searching the Decision Layer

The Hopsule CLI provides powerful tools for navigating your team's collective memory. Whether you are looking for a specific architectural rule or browsing the history of a project, the list and search functions ensure that organizational judgment is always accessible.

To view all decisions associated with your current project, use the hopsule decision list command. This will present a structured view of all decisions, categorized by their current lifecycle state: Draft, Pending, Accepted, or Deprecated. You can refine this view using various flags:

• Filter by State: Use flags to show only Accepted decisions to see what is currently enforceable, or Deprecated decisions to understand what has been superseded.

• Search by Keyword: Search through titles, descriptions, and memories to find specific context related to your current task.

• View Decision Details: Use the show command followed by a decision ID to view the full history, including all linked memories, version history, and the reasoning behind every change.

• Interactive TUI Dashboard: For a more visual experience, launch the interactive TUI dashboard. This terminal-based interface uses ASCII art and structured layouts to provide a real-time overview of your project's decision health and statistics.

The Decision Lifecycle: Accepting and Deprecating

The transition of a decision from a proposal to an enforceable constraint is a critical moment in governance. The Hopsule CLI allows authorized users to manage this lifecycle directly from the command line, ensuring that the team's memory remains current and authoritative.

Promoting to Accepted: When a team agrees on a decision, it must be moved to the Accepted state. Once accepted, the decision becomes an enforceable constraint. This means that Hopsule for VS Code and Hopsule MCP will begin surfacing this decision to developers and AI agents, ensuring that new code does not contradict established organizational judgment.

Deprecating Decisions: Organizations evolve, and decisions that were once vital may eventually become obsolete. However, Hopsule's philosophy is that "Enforcement is remembrance." Instead of deleting a decision, you Deprecate it. This moves the decision out of the active enforcement layer but preserves it and its associated memories in the Knowledge Graph. This ensures that the reasoning behind the old way of doing things is never lost, preventing the team from repeating past mistakes.

Managing Context Packs (Capsules)

Context Packs, or Capsules, are portable bundles of decisions and memories designed to survive time and system changes. The Hopsule CLI allows you to manage these capsules to share governance across different projects or teams.

1. Create a Capsule: Group related decisions and memories into a new Capsule. This is particularly useful for shared architectural patterns or company-wide standards.

2. Activate a Capsule: Link a Capsule to your current project. This instantly imports all decisions within that capsule into your local enforcement layer.

3. Freeze for History: When a project reaches a milestone, you can freeze a Capsule to create a historical snapshot of the team's decision state at that exact moment.

Enforcement and CI/CD Integration

The Hopsule CLI is not just a management tool; it is an enforcement engine. By integrating the CLI into your CI/CD pipelines, you can automate the verification of organizational constraints. The CLI can be configured to scan for contradictions or ensure that all new code changes are aligned with Accepted decisions. If a contradiction is detected, the CLI can provide a detailed report, citing the specific decision and the associated memories that explain why the constraint exists.

Tips and Best Practices

To maximize the effectiveness of the Hopsule CLI and ensure your team's memory remains a high-leverage asset, consider the following best practices:

• Atomic Decisions: Keep decisions focused and atomic. A single decision should represent a single commitment. This makes enforcement clearer and memories more relevant.

• Reasoning is Mandatory: Never accept a decision without an accompanying memory. The "why" is just as important as the "what." Without reasoning, a decision is just a rule; with reasoning, it is organizational wisdom.

• Regular Audits: Use the hopsule stats command to review the health of your decision layer. Identify decisions that have been in the Draft state for too long and either promote or discard them.

• Leverage the Knowledge Graph: Periodically check the Brain or Knowledge Graph in the Hopsule Dashboard to see how decisions and memories are interconnected. The CLI provides the data that fuels these visualizations.

• Use Hopper for Conflict Detection: Before promoting a decision to Accepted, ask Hopper to check for conflicts. This prevents the creation of contradictory constraints that can confuse the team and AI agents.

Troubleshooting

If you encounter issues while using the Hopsule CLI, refer to the following table for common resolutions. Most issues are related to authentication or network connectivity to the Hopsule API.

Related Articles

• Understanding the Decision Lifecycle: From Draft to Deprecated

• Using Hopsule for VS Code for Real-time Enforcement

• Creating and Distributing Context Packs (Capsules)

• Connecting AI Agents with Hopsule MCP