Hopsule CLI: Installation and Setup

Introduction to Hopsule CLI

The Hopsule CLI serves as the primary terminal-based interface for the Hopsule ecosystem, providing developers and engineering leaders with the ability to manage Decisions and Memories without departing from their local development environment. By integrating directly into the command line, Hopsule ensures that the preservation of organizational judgment is a seamless part of the engineering workflow. This tool is designed to facilitate the enforcement of Accepted Decisions and the creation of Context Packs (Capsules) during the active coding process, ensuring that the reasoning behind every architectural choice remains visible and actionable.

Beyond simple administrative tasks, the Hopsule CLI acts as a bridge between your local source code and the Knowledge Graph. It allows for the rapid drafting of new commitments, the retrieval of historical Memories, and the synchronization of project-specific constraints. Whether you are working as a solo developer or as part of a global engineering organization, the CLI provides the authoritative governance necessary to maintain consistency across distributed teams. This documentation provides a comprehensive guide to installing, configuring, and optimizing the Hopsule CLI for your specific operating system and workflow requirements.

System Requirements

Before initiating the installation of the Hopsule CLI, ensure that your environment meets the necessary technical specifications. The CLI is engineered for high performance and low resource consumption, but it requires a stable environment to maintain the integrity of the Context Packs it manages. Because Hopsule prioritizes security and data sovereignty, the CLI utilizes TLS 1.3 for all communications with the Hopsule Dashboard and requires local write permissions to manage its encrypted configuration files.

Supported Operating Systems include:

• macOS: 11.0 (Big Sur) or later, supporting both Intel and Apple Silicon architectures.

• Linux: Most modern distributions including Ubuntu 20.04+, Debian 10+, Fedora 32+, and CentOS Stream. The CLI is compatible with x86_64, ARM64, and ARMv7 architectures.

• Windows: Windows 10 or 11, including support for Windows Subsystem for Linux (WSL 2).

Network requirements are minimal but essential. The Hopsule CLI must be able to reach the Hopsule API endpoints to synchronize Decisions and Memories. If your organization operates behind a corporate firewall or proxy, ensure that outbound traffic is permitted for the standard HTTPS port (443). For Hopsule Enterprise (Self-Hosted) users, the CLI must have network visibility into your internal deployment infrastructure.

Installation Methods

Hopsule provides multiple installation vectors to accommodate different administrative preferences and organizational security policies. We recommend using a package manager where possible to simplify the process of future updates and dependency management. Each method ensures that the binary is correctly placed within your system's execution path, allowing for immediate access to the hopsule command.

macOS Installation via Homebrew

For users on macOS, Homebrew is the preferred method for managing the Hopsule CLI. This ensures that the tool remains updated with the latest governance features and security patches. To install, execute the following commands in your terminal:

1. Update your local Homebrew repositories: brew update

2. Install the Hopsule tap: brew tap hopsule/tap

3. Install the CLI: brew install hopsule

Tip: If you are using a managed machine where Homebrew is restricted, refer to the Direct Download method below for a standalone binary installation.

Linux Installation via Package Managers

Linux users can choose between native package managers or the Snap store, depending on their distribution's standards. For Debian-based systems such as Ubuntu, use the apt package manager. For other distributions, the snap command provides a cross-distribution solution that includes automatic background updates.

To install via apt, you must first add the Hopsule repository to your sources list. This ensures that your system recognizes Hopsule as a trusted provider of organizational memory tools. To install via snap, simply run:

sudo snap install hopsule

This will install the Hopsule CLI in a confined environment, providing an additional layer of security for your local Memories and Context Packs.

Windows Installation via Scoop or Chocolatey

On Windows environments, we recommend using Scoop or Chocolatey to manage the Hopsule CLI. These tools handle the complexities of path management and environment variables automatically. If you are using Scoop, execute:

scoop bucket add hopsule https://github.com/hopsule/scoop-bucket scoop install hopsule

For Chocolatey users, the command is similarly straightforward. Ensure you are running your terminal with administrative privileges to allow the package manager to register the hopsule command globally across your system.

Direct Binary Download

In environments where package managers are unavailable or restricted, you may download the pre-compiled binary directly from the Hopsule Dashboard. This method is often preferred for Hopsule Enterprise deployments where air-gapped or strictly controlled environments are common. After downloading the appropriate version for your architecture, move the binary to a directory in your PATH, such as /usr/local/bin on Unix-like systems or C:\Windows\System32 on Windows, and ensure it has execution permissions.

Verifying the Installation

Once the installation process is complete, it is critical to verify that the Hopsule CLI is correctly recognized by your operating system and that the version matches the current release provided by the Hopsule Dashboard. Verification ensures that all subsequent commands for managing Decisions will function as intended.

Run the following command in your terminal:

hopsule --version

The output should display the current version number and the build architecture. If the command is not found, verify that the installation directory is included in your system's PATH environment variable. For a more detailed status report, including the location of your configuration files and the status of your current session, you may run hopsule status. This command provides a high-level overview of the CLI's readiness to interact with your team's Knowledge Graph.

Initial Configuration and Authentication

Before the Hopsule CLI can begin enforcing Decisions or preserving Memories, it must be authenticated with your Hopsule account. This establishes a secure link between your local machine and the organizational memory layer, ensuring that every action you take is attributed to your identity and governed by your assigned roles.

Interactive Browser-Based Login

The standard method for authentication is the interactive login flow. This process uses your default web browser to securely exchange credentials, ensuring that your sensitive password information never touches the terminal directly. To initiate this process, run:

hopsule auth login

The CLI will generate a unique temporary code and open the Hopsule Dashboard in your browser. Once you confirm the login request, the CLI will receive a secure token, which is then stored in an encrypted format on your local machine using AES-256 encryption. This token allows the CLI to perform authorized actions on your behalf, such as drafting new Decisions or fetching Context Packs.

Token-Based Authentication for CI/CD

In automated environments such as CI/CD pipelines, interactive login is not possible. For these scenarios, Hopsule supports the use of Service Tokens. These tokens are generated within the Hopsule Dashboard under the Organization Settings and are designed for non-interactive use. They provide the CLI with the necessary authority to verify that incoming code changes do not contradict Accepted Decisions.

To use a Service Token, set the HOPSULE_TOKEN environment variable in your CI/CD configuration. The CLI will automatically detect this variable and bypass the interactive login requirement. This is essential for maintaining governance and remembrance during the automated build and deployment phases of your software lifecycle.

Important: Service Tokens should be treated with the same level of security as primary administrative credentials. Always use your CI/CD provider's "Secret" or "Protected Variable" feature to prevent the token from being exposed in build logs.

Configuration File Management

The Hopsule CLI maintains a local configuration file that stores your preferences, active project links, and organization-specific settings. Understanding the location and structure of this file is useful for troubleshooting and for advanced users who wish to customize their interaction with the Knowledge Graph.

The configuration file is managed automatically by the CLI, and manual editing is generally discouraged to prevent corruption of the local Memory cache. However, you can view your current configuration safely using the hopsule config list command. This will display your active organization, the current user identity, and any custom aliases you have created for frequently used Context Packs.

Connecting to Your Project

The true power of the Hopsule CLI is realized when it is linked to a specific engineering project. This connection allows the CLI to provide context-aware feedback and enforce Decisions that are relevant to the specific codebase you are working on. Without a project link, the CLI operates in a global mode, which is useful for general administration but lacks the granular enforcement required for high-stakes engineering.

To link your current working directory to a project defined in the Hopsule Dashboard, navigate to the root of your repository and execute:

hopsule project select

This command will present an interactive list of all projects you have permission to access. Once a project is selected, the CLI creates a hidden .hopsule reference file in the directory. This file does not contain sensitive data; it simply tells the CLI which Knowledge Graph nodes and Context Packs should be active for this directory. From this point forward, any Decisions you draft or Memories you record will be automatically associated with this project.

Tip: You can verify which project is currently active by looking at the TUI dashboard or by running hopsule project status. This will show you the number of Accepted Decisions currently being enforced in your environment.

Shell Completions

To enhance the developer experience and speed up the process of organizational remembrance, the Hopsule CLI supports shell completions for Bash, Zsh, Fish, and PowerShell. Completions allow you to use the Tab key to automatically fill in command names, flag options, and even the names of Decisions or Context Packs.

To enable completions, you must add a small snippet to your shell's configuration file. For example, if you are using Zsh, you can generate the completion script and add it to your .zshrc with the following command:

hopsule completion zsh > "${fpath[1]}/_hopsule"

After restarting your terminal or sourcing your configuration file, you will be able to navigate the Hopsule command structure with significantly greater efficiency. This is particularly useful when searching through a large volume of Memories or when you need to quickly find the ID of a Decision to deprecate it.

Updating the Hopsule CLI

Hopsule is a living system, and the CLI is frequently updated to support new capabilities in the Knowledge Graph and improved integration with Hopper, our advisory AI assistant. Maintaining an up-to-date version of the CLI is essential for ensuring that you have access to the latest security enhancements and Context Pack formats.

If you installed the CLI via a package manager like Homebrew or Scoop, use the standard update command for that tool (e.g., brew upgrade hopsule). If you installed via a direct binary download, you can use the built-in update command:

hopsule update

This command checks the Hopsule API for a newer version, downloads the appropriate binary for your system, and replaces the old version automatically. We recommend checking for updates at least once a month to stay aligned with the evolving standards of the Hopsule ecosystem.

Uninstalling the CLI

If you need to remove the Hopsule CLI from your system, the process is straightforward. Uninstalling the CLI will remove the executable binary but will not delete your Decisions or Memories, as these are securely preserved within the Hopsule Dashboard and the Knowledge Graph. Your organizational judgment remains intact even if the local interface is removed.

To uninstall via Homebrew: brew uninstall hopsule

To uninstall via Snap: sudo snap remove hopsule

After removing the binary, you may choose to manually delete the configuration directory (referenced in the Configuration File Management section) to remove all local traces of the CLI, including cached tokens and local Context Pack metadata. This is recommended if you are decommissioning a machine or transferring it to another user.

Next Steps

Now that the Hopsule CLI is installed and configured, you are ready to begin the work of preservation and enforcement. We recommend exploring the following documentation pages to deepen your understanding of the system:

• Managing Decisions via CLI: Learn how to draft, accept, and deprecate commitments directly from your terminal.

• Recording Memories: A guide to using the append-only memory system to capture the reasoning behind your technical choices.

• Working with Context Packs: How to bundle Decisions and Memories into portable Capsules for sharing across teams.

• Hopsule for VS Code: Integrate your CLI-managed decisions with your IDE for real-time enforcement and contradiction warnings.

The Hopsule CLI is your first step toward a more resilient engineering organization where decisions are not just made, but remembered and enforced. By bringing the Knowledge Graph to the terminal, Hopsule ensures that context is always at your fingertips.