CLI Authentication: Logging In and Managing Tokens

Introduction

The Hopsule CLI serves as the primary bridge between your local development environment and your organization's collective memory. Authentication is not merely a gatekeeping mechanism; it is the foundation of authority and traceability within the Hopsule ecosystem, ensuring that every decision made and every memory captured is attributed to a verified member of the engineering team. This article provides an exhaustive guide on how to establish, manage, and secure your CLI sessions to maintain the integrity of your organizational judgment.

By authenticating your Hopsule CLI, you enable the full suite of enforcement features, allowing the system to remind you of accepted decisions and prevent contradictions during the development lifecycle. Whether you are an individual developer working in solo mode or a leader overseeing a global engineering organization, understanding token management is critical for preserving context and ensuring that your team's decisions survive the passage of time and personnel changes.

Prerequisites

Before attempting to authenticate the Hopsule CLI, ensure that you have met the following requirements to facilitate a seamless connection to the Hopsule memory system:

• Active Hopsule Account: You must have an existing account on the Hopsule Dashboard. If you are part of an organization, ensure your administrator has invited you and your role has been defined.

• Hopsule CLI Installed: The CLI must be installed on your local machine. You can verify this by running hopsule --version in your terminal.

• Network Connectivity: Your environment must have outbound access to the Hopsule API to validate credentials and synchronize context packs.

• Web Browser Access: For the standard interactive login flow, a functional web browser is required to complete the secure handshake.

Interactive Authentication via the Terminal

The most common method for authenticating a local development machine is the interactive login flow. This method utilizes a secure browser-based handshake to link your terminal session with your Hopsule Dashboard identity without requiring you to manually handle long-lived secrets.

Step-by-Step Login Process

1. Open your preferred terminal emulator and type the command hopsule login.

2. The Hopsule CLI will generate a unique temporary device code and attempt to open your default web browser automatically. If the browser does not open, the CLI will provide a secure URL that you can copy and paste manually.

3. In the browser, you will be prompted to sign in to the Hopsule Dashboard if you are not already authenticated.

4. Once signed in, verify that the device code displayed in your browser matches the code shown in your terminal. This ensures that the authentication request originated from your machine and prevents unauthorized session hijacking.

5. Click the Authorize CLI button in the browser interface.

6. Return to your terminal. The Hopsule CLI will detect the successful authorization and synchronize your organizational context. You will see a confirmation message, often accompanied by ASCII art in the TUI (Terminal User Interface), indicating that your session is active.

Once authenticated, the CLI stores a secure session token in your machine's protected credential store. This token allows you to interact with your decisions, memories, and context packs without needing to re-authenticate for every command. The CLI will periodically refresh this session in the background to ensure uninterrupted access to the organizational memory layer.

Manual Token Management in the Hopsule Dashboard

For scenarios where interactive login is not feasible—such as remote servers, specialized IDE environments, or headless workstations—Hopsule provides the ability to generate Personal Access Tokens (PATs) directly from the Hopsule Dashboard. These tokens act as persistent keys to your organizational memory.

Generating a Personal Access Token

1. Log in to the Hopsule Dashboard via your web browser.

2. Navigate to the Settings menu, located in the sidebar or under your profile avatar in the top-right corner.

3. Select the API & Tokens tab within the settings interface.

4. Click the Create New Token button.

5. Provide a descriptive name for the token (e.g., "Home Office Workstation" or "Remote Dev Server"). This name will appear in the activity feed and Knowledge Graph, providing traceability for all actions performed using this token.

6. Select the appropriate scope for the token. You can choose between "Full Access" for managing the entire decision lifecycle or "Read-Only" for environments that only need to pull context packs and enforce existing decisions.

7. Set an expiration date if required by your organization's security policy. Hopsule recommends rotating tokens every 90 days to maintain high governance standards.

8. Click Generate Token.

9. Important: Copy the token immediately. For security reasons, Hopsule does not store the raw token value and will never show it to you again. If you lose the token, you must revoke it and generate a new one.

Applying the Token to the CLI

Once you have generated a token, you can provide it to the Hopsule CLI using the following command:

Alternatively, you can use the interactive setup wizard by running hopsule setup and selecting the "Manual Token Entry" option when prompted. This will securely write the token to your local configuration, enabling the CLI to act with your authority across all projects and capsules.

Authentication for CI/CD and Automated Environments

In modern engineering organizations, decisions must be enforced not only on local machines but also within the continuous integration pipeline. Hopsule CLI supports non-interactive authentication specifically designed for these automated environments, ensuring that no code is merged if it contradicts an Accepted decision.

Using Environment Variables

The Hopsule CLI is designed to look for specific environment variables before checking its local configuration file. This is the preferred method for authenticating in CI/CD platforms like GitHub Actions, GitLab CI, or Jenkins.

• HOPSULE_TOKEN: Set this variable to a Personal Access Token generated from the Hopsule Dashboard. This token should ideally have "Read-Only" or "Enforcement" scopes to follow the principle of least privilege.

• HOPSULE_ORG_ID: If your account is associated with multiple organizations, use this variable to specify which organizational memory the CLI should reference during the pipeline run.

When these variables are present, the Hopsule CLI will bypass the standard login check and proceed with the command using the provided credentials. This allows for seamless enforcement of decisions during the build or test phase, effectively turning your organizational memory into a persistent governance layer that prevents "decision drift" over time.

Managing Active Sessions and Revocation

Governance requires the ability to audit and revoke access at any time. Hopsule provides comprehensive tools within the Hopsule Dashboard to monitor which devices and tokens are currently accessing your team's memories.

Auditing Sessions

Within the API & Tokens section of the Hopsule Dashboard, you will find a list of all active sessions and generated tokens. Each entry includes:

• Name/Device: The identifier provided during token creation or the machine name detected during interactive login.

• Last Accessed: A timestamp of the most recent interaction with the Hopsule API.

• Created Date: When the session or token was first established.

• IP Address: The last known source of the connection (useful for identifying unauthorized access).

Revoking Access

If a device is lost, a team member leaves the organization, or a token is accidentally exposed in a public repository, you must revoke access immediately. To do this, click the Revoke or Delete button next to the corresponding entry in the Hopsule Dashboard. Once revoked, any CLI attempt to use that session or token will be met with an authentication error, and the local environment will lose access to the organizational memory until a new, authorized session is established.

Multi-Organization and Multi-Project Context

For senior developers and engineering leaders who operate across multiple organizations or projects, the Hopsule CLI supports complex authentication contexts. Hopsule remembers which organization you are currently acting within to ensure that decisions and memories remain isolated and relevant.

Switching Organizations

If your authenticated account has access to multiple organizations, you can switch the CLI's focus using the following command:

This will trigger an interactive TUI menu where you can select the active organization. The CLI will then update its local context, pulling the relevant Context Packs and Knowledge Graph data for that specific entity. This ensures that when you run hopsule decision list, you are seeing the commitments relevant to your current work environment, not a cluttered list of every decision you have ever been involved in.

Security and Preservation Standards

Hopsule treats authentication with the highest level of security, adhering to the philosophy that "Enforcement is remembrance, not control." However, remembrance requires a secure foundation. All authentication data handled by the Hopsule CLI and Hopsule API is protected by:

• End-to-End Encryption: Whether you are on a Free, Pro, or Enterprise plan, your authentication handshakes are encrypted using TLS 1.3.

• AES-256 Storage: At rest, Hopsule encrypts token metadata and session information using industry-standard AES-256 encryption.

• Data Sovereignty: For Hopsule Enterprise (Self-Hosted) users, all authentication traffic remains within your controlled infrastructure, ensuring that your organizational memory never leaves your environment.

• No Source Code Exposure: The Hopsule CLI and the Hopsule for VS Code extension process code locally. Authentication only grants access to decisions and memories; your actual source code is never sent to Hopsule servers for the purpose of authentication or enforcement.

Tips and Best Practices

To maintain a healthy and secure memory system, follow these best practices for CLI authentication:

• Use Descriptive Names: When generating tokens in the Hopsule Dashboard, always use specific names like "Laptop-MacBook-Pro-2023" rather than generic names like "Token1". This makes the Knowledge Graph and activity feeds much more insightful.

• Prefer Short-Lived Sessions: For daily development, use the hopsule login command. It creates session-based access that is easier to manage and more secure than long-lived manual tokens.

• Automate with Least Privilege: In CI/CD, use tokens with "Read-Only" scopes unless your pipeline is specifically designed to transition decisions (e.g., an automated script that moves a decision from Pending to Accepted based on test results).

• Regular Audits: Once a month, visit the API & Tokens section of the Hopsule Dashboard to prune old sessions and revoked tokens. This keeps your organizational authority clean and up to date.

• Leverage Hopper: If you are unsure if your CLI is properly authenticated, ask Hopper. Running hopsule hopper status will provide a quick summary of your current identity and the organization you are currently representing.

Troubleshooting

If you encounter issues while authenticating or using the Hopsule CLI, refer to the following table for common causes and solutions.

Related Articles

• Getting Started with Hopsule CLI: A Developer's Guide

• Managing the Decision Lifecycle: From Draft to Deprecated

• Understanding Context Packs (Capsules) and Portable Memory

• Configuring Hopsule for VS Code for Real-time Enforcement