Installing and Configuring Hopsule CLI

The Hopsule CLI is the primary bridge between your local development environment and your organization’s collective memory. By integrating decision enforcement and context preservation directly into the terminal, the CLI ensures that every engineer remains aligned with the team's authoritative governance without needing to context-switch to a web browser. This article provides a comprehensive guide to installing, authenticating, and mastering the Hopsule CLI to maintain organizational judgment across your entire engineering workflow.

Prerequisites

Before beginning the installation process, ensure that you have administrative privileges on your local machine to modify system paths and install binary files. Additionally, you must have an active account on the Hopsule Dashboard. If you are part of an enterprise organization, ensure your Hopsule Dashboard administrator has granted you the necessary permissions to generate API tokens. You will also need a stable internet connection to synchronize local context with the Hopsule central decision store, unless you are operating in a fully air-gapped Hopsule Enterprise (Self-Hosted) environment.

Installation Procedures

Hopsule CLI is distributed as a platform-agnostic binary, ensuring that enforcement and remembrance are available regardless of your operating system. Follow the specific instructions for your environment below.

macOS Installation

For macOS users, the Hopsule CLI can be installed via our official distribution channel. Open your terminal and execute the following command to retrieve and install the latest version of the Hopsule CLI:

curl -sL https://get.hopsule.com/install.sh | sh

This script automatically detects your architecture (Intel or Apple Silicon), downloads the appropriate binary, and moves it to your system path. Once the process completes, verify the installation by typing hopsule --version. You should see the current release version displayed, confirming that the tool is ready for configuration.

Linux Installation

On Linux systems, the installation process follows a similar pattern. We recommend using the automated installation script to ensure all necessary permissions are correctly set. Run the following in your shell:

wget -qO- https://get.hopsule.com/install.sh | sudo bash

If you prefer a manual installation, you can download the binary directly from the Hopsule Dashboard under the Downloads section. After downloading, move the binary to /usr/local/bin/hopsule and ensure it is executable by running chmod +x /usr/local/bin/hopsule.

Windows Installation

For Windows environments, the Hopsule CLI is provided as a standalone executable. Download the hopsule.exe file from the Hopsule Dashboard. We recommend placing this file in a dedicated directory, such as C:\Program Files\Hopsule, and adding that directory to your system's PATH environment variable. After updating your PATH, restart your terminal or PowerShell session and run hopsule version to confirm the system recognizes the command.

Authentication and Initial Configuration

Once the CLI is installed, you must link your local environment to your Hopsule account. This process establishes the secure, encrypted channel through which your team’s decisions and memories will flow.

1. Open your terminal and type hopsule auth login. This will launch a secure browser window pointing to the Hopsule Dashboard.

2. Log in using your corporate credentials. Once authenticated, the dashboard will display a unique authorization code.

3. Return to your terminal and paste the code when prompted. The CLI will then exchange this code for a long-lived, encrypted session token.

4. If you are working in a headless environment or a CI/CD pipeline, you should instead navigate to the Settings page in the Hopsule Dashboard, select API Tokens, and click the Create New Token button. Copy this token and set it as an environment variable named HOPSULE_TOKEN.

After successful authentication, you can configure your global preferences. Running hopsule config init will create a configuration file in your home directory. Here, you can define your default organization, preferred output formats (text or interactive TUI), and notification settings for when new decisions are accepted by your team.

Linking Projects and Initializing Context

Hopsule CLI operates on a project-by-project basis to ensure that the context provided is always relevant to the task at hand. To link a local code repository to a Hopsule project, navigate to the root directory of your project and execute:

hopsule project link

The CLI will present an interactive list of projects available to you on the Hopsule Dashboard. Select the appropriate project to create a local link. This action creates a hidden configuration entry that tells the CLI which Context Packs and Decisions should be enforced within this directory. Once linked, you can run hopsule status to see a summary of the project’s current governance state, including the number of Accepted Decisions and any Pending drafts that require your review.

Managing the Decision Lifecycle via CLI

The Hopsule CLI is not merely a viewer; it is a powerful tool for participating in organizational governance. It supports the full lifecycle of a decision, from draft to deprecation.

Creating and Reviewing Decisions

When you encounter a situation that requires a formal commitment, you can initiate a new decision directly from the terminal. Run hopsule decision create to open the interactive editor. You will be prompted to provide a title, a description, and the reasoning behind the decision. This reasoning is automatically captured as a Memory, ensuring that future team members understand the "why" behind the "what."

To view existing decisions, use hopsule decision list. This command provides a filtered view of all active constraints. For a more immersive experience, hopsule dashboard (within the CLI) launches a terminal-based user interface (TUI) that allows you to browse the Knowledge Graph, visualizing how different decisions are interconnected.

Accepting and Deprecating

Decisions in Hopsule move through states. If you have the necessary authority, you can accept a pending decision by running hopsule decision accept [ID]. Once accepted, the decision becomes an enforceable constraint that will be visible in Hopsule for VS Code and validated during Hopsule CLI status checks. Conversely, when a decision is no longer relevant, use hopsule decision deprecate [ID]. This moves the decision into the historical record, preserving it as part of the organizational memory while removing it from active enforcement.

Utilizing Hopper in the Terminal

Hopper, the Hopsule AI assistant, is fully integrated into the CLI to provide advisory context. If you are unsure why a specific constraint exists, you can ask Hopper for clarification without leaving your workflow. Execute hopsule ask "Why do we use asynchronous processing for this service?". Hopper will query your project’s Memories and Decisions to provide a response rooted in your team’s actual history.

It is important to remember that Hopper is strictly advisory. While it can suggest improvements to a decision draft or identify potential conflicts between two proposed decisions, it never has the authority to accept or mutate a decision autonomously. The power of judgment remains entirely with the human team members.

Advanced Usage: Context Packs and CI/CD

For large organizations, managing decisions across hundreds of repositories can be challenging. This is where Context Packs (or Capsules) become essential. A Capsule is a portable bundle of decisions and memories that can be shared across multiple projects. Using the CLI, you can "pull" a specific Capsule into your project with hopsule capsule pull [CAPSULE_NAME]. This allows you to inherit global engineering standards or specific architectural patterns instantly.

Furthermore, the Hopsule CLI is designed to be a gatekeeper in your CI/CD pipelines. By adding hopsule check to your build scripts, you can ensure that no code is merged that contradicts an Accepted Decision. If the CLI detects a violation, it will exit with a non-zero status code and provide a detailed report of the contradiction, effectively enforcing remembrance at the point of integration.

Tips and Best Practices

• Frequent Synchronization: Run hopsule sync at the start of every workday to ensure your local cache of decisions is up to date with the Hopsule Dashboard.

• Meaningful Memories: When creating a decision, provide exhaustive reasoning in the memory field. Remember that "Enforcement is remembrance," and future developers will rely on these entries to understand the context of today's constraints.

• Use Solo Mode: Even if you are working on a personal project, use the CLI's solo mode to track your own architectural decisions. This builds a personal memory bank that you can later export into a Context Pack for a team.

• Leverage the TUI: The interactive TUI (hopsule dashboard) is often faster for browsing complex decision trees than the web interface. Use the Knowledge Graph view to identify circular dependencies in your team's logic.

• Integrate with Git: Use Hopsule CLI hooks to automatically check for decision compliance before every commit. This catches contradictions before they ever reach the remote repository.

Troubleshooting

If you encounter issues while using the Hopsule CLI, consult the table below for common resolutions.

Related Articles

• Managing API Tokens and Permissions

• Integrating Hopsule CLI into GitHub Actions

• Understanding the Decision Lifecycle: From Draft to Deprecated