Hopsule CLI Commands Reference

Overview of the Hopsule CLI

The Hopsule CLI is the primary terminal interface for interacting with your organization's decision and memory layer. It is designed to integrate seamlessly into the developer workflow, allowing for the creation, enforcement, and preservation of organizational judgment without requiring a context switch to a web browser. By using the Hopsule CLI, engineering teams ensure that every decision is traceable, every memory is preserved, and every context pack is portable across the entire development lifecycle.

This reference guide provides an exhaustive breakdown of all available commands, flags, and configuration options. Whether you are automating decision governance in a CI/CD pipeline or interacting with the interactive TUI dashboard during local development, the Hopsule CLI serves as the authoritative bridge between your code and your team's collective memory.

Prerequisites

Before utilizing the Hopsule CLI, ensure the following requirements are met to maintain the integrity of your decision environment:

• Active Hopsule Account: You must have a registered account and belong to an organization within the Hopsule Dashboard.

• Personal Access Token: Authentication requires a secure token. You can generate this by navigating to Settings > Developer Access in the Hopsule Dashboard.

• Terminal Environment: A modern terminal emulator supporting TLS 1.3 for secure communication with the Hopsule API.

• Context Awareness: Ensure you are working within a project directory that corresponds to an existing Capsule (Context Pack) if you intend to link decisions to specific project scopes.

Core Command Reference

The Hopsule CLI is structured around the three core entities: Decisions, Memories, and Capsules. All commands follow a consistent syntax: hopsule [entity] [action] [flags].

1. Authentication and Configuration

Governance begins with identity. These commands manage your session and ensure your terminal is authorized to access the organizational memory.

hopsule auth login

Initializes a secure session. You will be prompted to enter your Personal Access Token. This token is stored using system-level encryption to ensure data at rest remains secure.

• --token [string]: Provide the token directly via the command line (useful for non-interactive environments).

• --org [ID]: Set the default organization context for the session.

hopsule auth status

Displays the current authentication state, including the active user, organization, and token expiration status. This is the primary command for verifying that your CLI is correctly connected to the Hopsule API.

hopsule config

Manages local CLI preferences. This does not affect the organizational memory but changes how the Hopsule CLI displays information.

• --output [text|json]: Switches between human-readable tables and machine-readable JSON. Use JSON for integration with other shell scripts.

• --editor [string]: Sets the default text editor for drafting long-form decisions or memories (e.g., vim, nano, code).

2. Decision Governance

Decisions are explicit commitments. The CLI allows you to manage the entire lifecycle of a decision, from an initial draft to an enforced constraint.

hopsule decision list

Displays a searchable table of all decisions within the current context. By default, it shows active and accepted decisions.

• --status [draft|pending|accepted|deprecated]: Filter decisions by their current lifecycle stage.

• --capsule [ID]: View decisions belonging to a specific Context Pack.

• --search [query]: Perform a full-text search across decision titles and descriptions.

hopsule decision create

Initiates a new decision. Every decision created via the CLI starts in the Draft state unless the --accept flag is used by an authorized user.

• --title "[string]": The concise name of the decision (e.g., "Standardize on PascalCase for Types").

• --context "[string]": The initial reasoning or problem statement.

• --capsule [ID]: The Context Pack this decision should be bundled into.

• --draft: Explicitly marks the decision as a draft for further refinement (default).

• --hopper: Invokes Hopper, the built-in AI assistant, to help refine the wording and detect potential conflicts with existing decisions.

hopsule decision accept [ID]

Moves a decision from Pending to Accepted. This is a critical governance action. Once accepted, the decision becomes an enforceable constraint that will surface in Hopsule for VS Code.

• --reasoning "[string]": A mandatory field explaining why the decision was accepted at this time. This is preserved as a Memory.

• --override: Allows an administrator to bypass standard pending periods if necessary.

hopsule decision deprecate [ID]

Marks a decision as Deprecated. Hopsule never deletes decisions; deprecation preserves the history while signaling that the commitment is no longer active. This ensures that future developers can see what was previously decided and why it changed.

• --superseded-by [ID]: Links the deprecated decision to a new, active decision for traceability.

3. Memory Preservation

Memories provide the "Why." They are append-only entries that ensure the reasoning behind your governance is never lost. Use these commands to add context to your decisions.

hopsule memory add

Appends a new memory entry to a specific decision or capsule.

• --decision [ID]: Links the memory to a specific decision.

• --capsule [ID]: Links the memory to a broader Context Pack.

• --content "[string]": The text of the memory. This should include data, links to external discussions, or lessons learned.

• --type [reasoning|history|lesson]: Categorizes the memory for better visualization in the Knowledge Graph.

hopsule memory list

Retrieves the chronological history of memories for a given entity. This provides the full audit trail of how a decision evolved over time.

4. Capsule Management (Context Packs)

Capsules are the portable units of Hopsule. They allow you to bundle decisions and memories for specific projects or teams.

hopsule capsule pull [ID]

Synchronizes a specific Context Pack to your local environment. This is often used in CI/CD pipelines to ensure the build environment is aware of the latest decisions for enforcement checks.

hopsule capsule push [ID]

Uploads local changes to a Context Pack to the Hopsule Dashboard. This requires appropriate permissions and is used when managing capsules in "Draft" or "Active" states.

hopsule capsule freeze [ID]

Sets a Capsule to the Frozen state. No further decisions or memories can be added. This is used for archiving the context of completed projects or specific releases.

5. Interactive TUI (The Dashboard)

hopsule dashboard

Launches the interactive Terminal User Interface (TUI). This provides a visual representation of the Knowledge Graph using ASCII art and allows for rapid navigation between decisions and memories. The dashboard is the preferred way for developers to explore the "Brain" of their organization without leaving the CLI.

• Navigation: Use arrow keys or HJKL.

• Search: Press '/' to enter search mode.

• Actions: Press 'e' to edit a draft or 'a' to accept a pending decision.

Advanced Usage: CI/CD Integration

The Hopsule CLI is designed to be the enforcement arm of your governance strategy in automated environments. By integrating the CLI into your CI/CD pipelines, you can prevent code that contradicts accepted decisions from being merged.

1. Authentication: Use a Service Token stored as a secret environment variable (HOPSULE_TOKEN).

2. Context Loading: Run hopsule capsule pull [ID] at the start of the pipeline to load the current decision set.

3. Enforcement Check: Use the hopsule decision check command (available in the API-integrated CLI) to scan the diff for contradictions. If a contradiction is found, the CLI returns a non-zero exit code, failing the build.

4. Remembrance Logging: Automatically append build metadata or deployment logs as memories using hopsule memory add --type history.

Tips and Best Practices

• Enforcement is Remembrance: Use the --reasoning flag every time you accept or deprecate a decision. The "why" is often more valuable than the "what" three months down the line.

• Leverage Hopper: When creating a decision via hopsule decision create --hopper, the AI assistant will check if your new decision contradicts an existing one. This prevents "governance drift."

• Use JSON for Automation: When scripting, always use --output json. This allows you to pipe the output into tools like jq for complex workflows.

• Link Everything: Never create a memory in isolation. Always link it to a decision or a capsule to ensure it appears in the Knowledge Graph.

• Solo Mode: If you are an individual developer, use a single "Personal" Capsule to track your own architectural decisions. Hopsule CLI works just as effectively for solo context preservation as it does for large teams.

• Atomic Decisions: Keep decisions small and focused. Instead of one large "Backend Policy," create several atomic decisions like "Use UUIDv7 for Primary Keys" and "Standardize on UTC for Timestamps."

Troubleshooting

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

Related Articles

• Integrating Hopsule for VS Code with the CLI

• Managing the Decision Lifecycle: From Draft to Deprecated

• Using Hopsule MCP to Connect AI Agents to Your Memories

• Visualizing Context: A Guide to the Knowledge Graph