raindrop annotation

The raindrop annotation command manages application metadata using Machine Resource Names (MRNs). Store structured metadata, configuration, documentation, or any text data associated with your Raindrop applications and resources.

Annotations use MRNs to uniquely identify metadata. MRNs provide a hierarchical naming system that maps to your application structure.

Machine Resource Names (MRNs)

MRNs uniquely identify annotations with this format:

annotation:app-name:version:module:item^key:

MRN Components:

• annotation - Resource type (always “annotation”)
• app-name - Application name
• version - Application version
• module - Module name within application
• item - Specific item (optional, separated by ^)
• key - Annotation key

Partial MRNs:

You can use partial MRNs and the CLI infers application/version from your manifest and config:

# Partial MRN (infers app and version)
my-module:my-key:

# Full MRN (explicit everything)
annotation:my-app:v1.0.0:my-module:my-key:

# With item specifier
my-module:my-item^my-key:

Basic Usage

Store an annotation:

raindrop annotation put my-module:config: "Production configuration"

Retrieve an annotation:

raindrop annotation get my-module:config:

List annotations:

raindrop annotation list my-module

Command Reference

raindrop annotation get

Retrieve an annotation by MRN.

Syntax:

raindrop annotation get <mrn> [--format <format>] [--manifest <path>]

Arguments:

• <mrn> - MRN of annotation to retrieve (partial or full) (required)

Flags:

Flag	Description	Values	Default
-f, --format	Output format	text, json	text
-m, --manifest	Manifest file path	Path	raindrop.manifest

Examples:

# Get with partial MRN
raindrop annotation get my-module:config:

# Get with full MRN
raindrop annotation get annotation:my-app:v1.0.0:my-module:config:

# Get with item specifier
raindrop annotation get my-module:my-item^description:

# Get as JSON
raindrop annotation get my-module:config: --format json

Output (text):

MRN: annotation:my-app:v1.0.0:my-module:config:
Value: Production configuration
Created: 2025-10-23T10:30:00.000Z
Modified: 2025-10-23T15:45:00.000Z

Output (JSON):

{
  "mrn": "annotation:my-app:v1.0.0:my-module:config:",
  "value": "Production configuration",
  "createdAt": "2025-10-23T10:30:00.000Z",
  "modifiedAt": "2025-10-23T15:45:00.000Z"
}

---

raindrop annotation put

Create or update an annotation.

Syntax:

raindrop annotation put <mrn> <annotation> [--output <format>] [--manifest <path>]

Arguments:

• <mrn> - MRN of annotation (partial or full) (required)
• <annotation> - Annotation content (use - for stdin, @filename for file) (required)

Flags:

Flag	Description	Values	Default
-o, --output	Output format	text, json	text
-m, --manifest	Manifest file path	Path	raindrop.manifest

Examples:

# Create annotation with inline text
raindrop annotation put my-module:config: "Production configuration"

# Create with full MRN
raindrop annotation put annotation:my-app:v1.0.0:my-module:config: "Value"

# Read from stdin
echo "Configuration data" | raindrop annotation put my-module:config: -

# Read from file
raindrop annotation put my-module:docs: @README.md

# Read multiline from stdin (heredoc)
raindrop annotation put my-module:config: - << EOF
{
  "database": "postgres://localhost/mydb",
  "apiKey": "secret123"
}
EOF

# Create with item specifier
raindrop annotation put my-module:handler-1^docs: "Handler documentation"

Output:

✓ Annotation created/updated successfully

MRN: annotation:my-app:v1.0.0:my-module:config:

Reading from Stdin:

Use - as the annotation value to read from stdin:

# Interactive input (Ctrl+D to finish)
raindrop annotation put my-module:notes: -
Type your notes here...
Multiple lines supported...
<Ctrl+D>

# Piped input
cat config.json | raindrop annotation put my-module:config: -

# Heredoc
raindrop annotation put my-module:readme: - << 'EOF'
# My Module
Documentation goes here
EOF

---

raindrop annotation list

List annotations by MRN prefix.

Syntax:

raindrop annotation list [mrnPrefix] [--output <format>] [--limit <number>] [--manifest <path>]

Arguments:

• [mrnPrefix] - MRN prefix to filter by (optional, uses app/version from config if omitted)

Flags:

Flag	Description	Values	Default
-o, --output	Output format	table, text, json	table
-l, --limit	Maximum annotations to return	Number	100
-m, --manifest	Manifest file path	Path	raindrop.manifest

Examples:

# List all annotations for current app/version
raindrop annotation list

# List annotations for specific module
raindrop annotation list my-module

# List with full prefix
raindrop annotation list annotation:my-app:v1.0.0:my-module

# List as JSON
raindrop annotation list my-module --output json

# Limit results
raindrop annotation list my-module --limit 10

Output (table):

┌──────────────────────────────────────────────────┬──────────────────────────┬──────────────────────────┐
│ MRN                                              │ Created                  │ Modified                 │
├──────────────────────────────────────────────────┼──────────────────────────┼──────────────────────────┤
│ annotation:my-app:v1.0.0:my-module:config:       │ 2025-10-23T10:30:00.000Z │ 2025-10-23T15:45:00.000Z │
│ annotation:my-app:v1.0.0:my-module:docs:         │ 2025-10-23T09:15:00.000Z │ 2025-10-23T09:15:00.000Z │
│ annotation:my-app:v1.0.0:my-module:metadata:     │ 2025-10-22T14:20:00.000Z │ 2025-10-23T11:30:00.000Z │
└──────────────────────────────────────────────────┴──────────────────────────┴──────────────────────────┘

Output (text):

MRN: annotation:my-app:v1.0.0:my-module:config:
  Created: 2025-10-23T10:30:00.000Z
  Modified: 2025-10-23T15:45:00.000Z

MRN: annotation:my-app:v1.0.0:my-module:docs:
  Created: 2025-10-23T09:15:00.000Z
  Modified: 2025-10-23T09:15:00.000Z

Use Cases

Configuration Storage

Store configuration data for modules:

# Store database configuration
raindrop annotation put my-module:db-config: - << EOF
{
  "host": "localhost",
  "port": 5432,
  "database": "myapp"
}
EOF

# Retrieve configuration
raindrop annotation get my-module:db-config: --format json

Documentation

Attach documentation to modules:

# Store module documentation
raindrop annotation put my-module:readme: @MODULE_README.md

# Store API documentation
raindrop annotation put api-handler:docs: @API_DOCS.md

# Retrieve and view
raindrop annotation get my-module:readme:

Metadata

Track deployment metadata:

# Record deployment info
raindrop annotation put app:deployment-info: "Deployed by CI/CD on $(date)"

# Track version notes
raindrop annotation put app:release-notes: - << EOF
## Version 1.2.0

- Added user authentication
- Fixed database connection pooling
- Updated dependencies
EOF

# Query deployment history
raindrop annotation list app:deployment

Feature Flags

Store feature flag configurations:

# Enable feature
raindrop annotation put app:features^new-ui: "enabled"

# Disable feature
raindrop annotation put app:features^beta-api: "disabled"

# List all feature flags
raindrop annotation list app:features

Environment-Specific Notes

Store environment-specific information:

# Production notes
raindrop annotation put prod-handler:notes: "Uses production database, requires API key"

# Development notes
raindrop annotation put dev-handler:notes: "Uses local database, no auth required"

# View notes
raindrop annotation get prod-handler:notes:

Common Workflows

Bulk Annotation Creation

Create multiple annotations from a directory:

#!/bin/bash
# annotate-docs.sh - Annotate modules with documentation files

MODULE="my-module"
DOCS_DIR="./docs"

# Annotate each documentation file
for doc in "$DOCS_DIR"/*.md; do
  basename=$(basename "$doc" .md)
  echo "Annotating: $MODULE:$basename:"

  raindrop annotation put "$MODULE:$basename:" "@$doc"
done

Configuration Management

Manage configurations across environments:

# Store production config
raindrop annotation put app:config^production: @config/production.json

# Store staging config
raindrop annotation put app:config^staging: @config/staging.json

# Store development config
raindrop annotation put app:config^development: @config/development.json

# List all configs
raindrop annotation list app:config

Annotation Backup

Backup annotations to local files:

#!/bin/bash
# backup-annotations.sh - Backup all annotations

OUTPUT_DIR="./annotation-backup"
mkdir -p "$OUTPUT_DIR"

# Get list of annotations
annotations=$(raindrop annotation list --output json | jq -r '.[].mrn')

# Download each annotation
echo "$annotations" | while read mrn; do
  # Sanitize MRN for filename
  filename=$(echo "$mrn" | tr ':' '_' | tr '^' '_')

  echo "Backing up: $mrn"
  raindrop annotation get "$mrn" > "$OUTPUT_DIR/$filename.txt"
done

echo "Backup complete: $OUTPUT_DIR"

Annotation Restore

Restore annotations from backup:

#!/bin/bash
# restore-annotations.sh - Restore annotations from backup

BACKUP_DIR="./annotation-backup"

# Restore each annotation
for file in "$BACKUP_DIR"/*.txt; do
  # Extract MRN from filename
  mrn=$(basename "$file" .txt | tr '_' ':')

  echo "Restoring: $mrn"
  raindrop annotation put "$mrn" - < "$file"
done

echo "Restore complete"

Search Annotations

Search annotation content:

# List all annotations and search content
raindrop annotation list --output json | \
  jq -r '.[].mrn' | \
  while read mrn; do
    content=$(raindrop annotation get "$mrn")
    if echo "$content" | grep -q "production"; then
      echo "Found in: $mrn"
      echo "$content"
      echo "---"
    fi
  done

Best Practices

Naming Conventions:

• Use descriptive module names in MRNs
• Employ consistent key naming (e.g., config, docs, metadata)
• Use item specifiers (^) for related groupings
• Follow kebab-case for readability

Data Storage:

• Store small to medium-sized text data
• Use structured formats (JSON, YAML) for complex data
• Avoid storing binary data
• Keep annotations focused and single-purpose

Version Management:

• Version-specific annotations for configuration changes
• Use current version for active documentation
• Archive old versions for history
• Copy annotations when branching

Security:

• Never store secrets or credentials in annotations
• Use environment variables for sensitive data
• Review annotations before sharing projects
• Implement access controls at organization level

Organization:

• Group related annotations with common prefixes
• Document annotation schema for your project
• Create indexes with list operations
• Clean up unused annotations regularly

MRN Format Reference

Full MRN:
annotation:app-name:version:module:item^key:
│          │        │       │      │    │
│          │        │       │      │    └─ Annotation key
│          │        │       │      └────── Optional item specifier
│          │        │       └───────────── Module name
│          │        └───────────────────── Version ID
│          └────────────────────────────── Application name
└───────────────────────────────────────── Resource type

Partial MRN (app/version inferred):
module:key:
module:item^key:

Item Specifier (^):
module:item1^key:    - Annotation for item1
module:item2^key:    - Annotation for item2
module:^key:         - Annotation without specific item

Exit Codes

Code	Description
0	Command completed successfully
1	General error (annotation not found, invalid MRN, etc.)
2	Invalid arguments