# How to Add an Annotation in Context Hub: Command Syntax and Examples

> Learn the Context Hub command to add annotations. Discover syntax and examples for chuh annotate id note to streamline your workflow.

- Repository: [Andrew Ng/context-hub](https://github.com/andrewyng/context-hub)
- Tags: how-to-guide
- Published: 2026-03-20

---

**To add an annotation in Context Hub, run `chub annotate <id> "<note>"` where `<id>` is the entry identifier and `<note>` is your annotation text.**

Context Hub, developed by Andrew Ng's team at `andrewyng/context-hub`, is an open-source CLI tool for managing contextual documents and AI skills. Adding annotations allows you to attach persistent local notes to any entry, ensuring important context survives across sessions and appears automatically in future `chub get` calls.

## The `chub annotate` Command Syntax

The primary interface for adding annotations is the `chub annotate` command, registered in [`cli/src/commands/annotate.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/commands/annotate.js).

### Basic Usage

To attach a note to a specific entry:

```bash
chub annotate <id> "<note>"

```

For example, to annotate the Stripe API entry:

```bash
chub annotate stripe/api "Needs raw body for webhook verification"

```

### Command Flags

The `annotate` command supports several flags defined in the command registration:

- `--clear` – Removes the annotation for the specified ID
- `--list` – Displays all stored annotations
- `--json` – Outputs results in JSON format instead of human-readable text

## How Annotations Work Under the Hood

When you run `chub annotate`, the system executes a precise workflow involving several core library modules.

### Command Registration and Parsing

In [`cli/src/commands/annotate.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/commands/annotate.js), the `registerAnnotateCommand` function handles argument parsing and flag detection. It validates the input and delegates to the appropriate library functions based on whether `--clear`, `--list`, or a standard annotation is requested.

### Annotation Storage Logic

The [`cli/src/lib/annotations.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/annotations.js) file implements the CRUD operations:

- `writeAnnotation(id, note)` – Creates or overwrites the JSON file for the given ID
- `readAnnotation(id)` – Retrieves the annotation data
- `clearAnnotation(id)` – Deletes the annotation file
- `listAnnotations()` – Returns all stored annotations

### Configuration and File Paths

The [`cli/src/lib/config.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/config.js) module provides `getChubDir()`, which resolves to the user's `~/.chub` directory. Annotations are stored as individual JSON files inside `~/.chub/annotations/`, with filenames derived from the entry ID.

### Output Formatting

After operations complete, [`cli/src/lib/output.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/output.js) formats the results. The `output()` function handles the `--json` flag to switch between terminal-friendly text and structured JSON output.

## Practical Examples

### Adding Your First Annotation

Attach a reminder to a specific API documentation entry:

```bash
chub annotate openai/api-v2 "Check rate limit headers before production deploy"

```

### Clearing an Annotation

Remove a note when it is no longer relevant:

```bash
chub annotate openai/api-v2 --clear

```

### Listing All Annotations

Review all your stored notes across entries:

```bash
chub annotate --list

```

### Programmatic Access

You can interact with annotations directly in JavaScript:

```javascript
import { readAnnotation, writeAnnotation } from '@aisuite/chub/cli/src/lib/annotations.js';

// Write an annotation
writeAnnotation('stripe/api', 'Verify webhook signatures');

// Read it back
const ann = readAnnotation('stripe/api');
console.log(ann.note);  // "Verify webhook signatures"
console.log(ann.updatedAt);  // ISO timestamp

```

## Summary

- Use `chub annotate <id> "<note>"` to attach persistent notes to any Context Hub entry.
- Annotations are stored as JSON files in `~/.chub/annotations/` and managed via [`cli/src/lib/annotations.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/annotations.js).
- The `annotate` command supports `--clear`, `--list`, and `--json` flags for full CRUD operations.
- All annotations automatically appear in future `chub get` calls for the annotated entry.

## Frequently Asked Questions

### Where are annotations stored locally?

Annotations are stored as individual JSON files in the `~/.chub/annotations/` directory. Each file corresponds to a single entry ID and contains the note text and timestamp. This path is determined by the `getChubDir()` function in [`cli/src/lib/config.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/config.js).

### Can I overwrite an existing annotation?

Yes. Running `chub annotate <id> "<new-note>"` on an ID that already has an annotation will overwrite the previous JSON file with the new content and updated timestamp. The `writeAnnotation` function in [`cli/src/lib/annotations.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/annotations.js) handles this automatically.

### How do I view annotations when retrieving an entry?

When you run `chub get <id>`, any existing annotation for that ID automatically appears in the output. The retrieval logic checks the `~/.chub/annotations/` directory for a matching file and displays the note alongside the entry content.

### Is there a way to export annotations?

While there is no dedicated export command, you can use `chub annotate --list --json` to output all annotations as structured JSON to stdout, which you can redirect to a file for backup or processing. The `--json` flag triggers the JSON formatter in [`cli/src/lib/output.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/output.js).