CLI
Manage your plants from the terminal. The Rootnotes CLI wraps the REST API and MCP tools into a single command-line interface.
Installation
npm install -g @timbenniks/rootnotes
Requires Node.js 18 or later. Or run directly with npx:
npx @timbenniks/rootnotes --help
Authentication
Generate a token from Settings → AI Clients in the app, then log in. Tokens must start with tnd_mcp_.
# Interactive login — stores token in ~/.rootnotes/config.json rootnotes auth login # Check current auth status rootnotes auth status # Remove stored credentials rootnotes auth logout
You can also set the ROOTNOTES_TOKEN environment variable or pass --token on any command. Resolution order: --tokenflag → environment variable → stored config.
Global options
| Option | Description |
|---|---|
| --json | Output as JSON (for piping to jq, scripts, etc.) |
| --no-color | Disable colored output |
| --api-url <url> | Override the API base URL (default: rootnotes.app) |
| --token <token> | Use a specific token instead of the stored one |
Commands
Plants
# List all plants rootnotes plants list # Get detailed info for a plant rootnotes plants get <plant-id> # Search by name, species, or location rootnotes plants search "monstera" # Create a new plant rootnotes plants create --name "Monstera" \ --species "Monstera deliciosa" \ --location "Living room" \ --watering-days 7 \ --light bright_indirect # Update specific fields rootnotes plants update <plant-id> --watering-days 10 --location "Bedroom" # Delete a plant (prompts for confirmation) rootnotes plants delete <plant-id> rootnotes plants delete <plant-id> --yes # skip confirmation
| Option | Description |
|---|---|
| -n, --name <name> | Plant name (required for create) |
| --species <species> | Species name |
| --location <location> | Physical location |
| --notes <notes> | Notes about the plant |
| --watering-days <days> | Watering frequency in days |
| --light <level> | Light requirement: low, medium, bright_indirect, full_sun |
Events
# List events for a plant (default: 20) rootnotes events list <plant-id> rootnotes events list <plant-id> --limit 50 # Add a care event rootnotes events add <plant-id> --type watered rootnotes events add <plant-id> --type fertilized --text "Half-strength feed" rootnotes events add <plant-id> --type repotted --date 2026-03-20T10:00:00Z # Delete an event (soft delete) rootnotes events delete <event-id>
Event types: watered, fertilized, repotted, soil_change, note, journal, growth
| Option | Description |
|---|---|
| -t, --type <type> | Event type (required) |
| --text <text> | Optional note text |
| --date <date> | Event date in ISO 8601 format (defaults to now) |
| -n, --limit <count> | Number of events to return (default: 20) |
Insights
# Account-wide stats and attention list rootnotes insights overview # Per-plant summary (recent activity, event counts) rootnotes insights summary <plant-id> # Aggregate stats (no plant ID) rootnotes insights summary
AI tools (requires Pro)
AI commands communicate via the MCP endpoint for plant identification, care profiles, and light analysis.
# Identify a plant from an image URL rootnotes ai identify <image-url> rootnotes ai identify <image-url> --hint "tropical, large leaves" # Look up a care profile for a species rootnotes ai care-profile "Monstera deliciosa" # Apply a care profile to a plant rootnotes ai set-care <plant-id> --species "Monstera deliciosa" rootnotes ai set-care <plant-id> --species "Monstera deliciosa" --overwrite # Analyze light conditions from an image rootnotes ai light <image-url> rootnotes ai light <image-url> --hint "south-facing window" # Check if observed light matches a plant's requirements rootnotes ai light-match --observed bright_indirect --required medium rootnotes ai light-match --observed low --required full_sun --species "Ficus" # Identify + create a plant in one command rootnotes ai add-from-image <image-url> rootnotes ai add-from-image <image-url> --name "Kitchen Fern" --location "Kitchen"
| Option | Description |
|---|---|
| --hint <hint> | Optional hint for identification or light analysis |
| --species <species> | Species name (for set-care and light-match) |
| --overwrite | Overwrite existing care data when applying a profile |
| --observed <level> | Observed light level (for light-match) |
| --required <level> | Required light level (for light-match) |
| --name <name> | Plant name for add-from-image (auto-generated if omitted) |
| --location <location> | Plant location for add-from-image |
Light levels: low, medium, bright_indirect, full_sun
Export
# Print all account data as JSON to stdout rootnotes export # Write to a file rootnotes export -o backup.json
Configuration
The CLI stores configuration in ~/.rootnotes/config.json:
{
"apiUrl": "https://rootnotes.app",
"token": "tnd_mcp_...",
"scopes": ["plants:read", "plants:write", "events:write", "insights:read"]
}| Option | Description |
|---|---|
| ROOTNOTES_TOKEN | Environment variable — overrides stored token |
| ROOTNOTES_API_URL | Environment variable — overrides stored API URL |
Error handling
The CLI translates API errors into friendly messages with suggested actions.
| Error | Message |
|---|---|
| 401 | Authentication failed — run rootnotes auth login |
| 403 (scope) | Permission denied — regenerate token with required scopes |
| 403 (feature) | Feature not available on your plan — requires Pro |
| 403 (limit) | Plant limit reached — upgrade your plan |
| 404 | Resource not found |
| 429 | Rate limited — wait and retry |
Examples
Morning watering workflow
# Find plants that need watering rootnotes plants list --json | jq '.[] | select(.lastWatered == null) | .name' # Log watering for a plant rootnotes events add <plant-id> --type watered
Add a plant from a photo
# AI identifies the plant, creates it, and applies a care profile rootnotes ai add-from-image https://example.com/my-plant.jpg \ --name "Living Room Fern" --location "Living room"
Check light compatibility
# Analyze light from a photo, then check against a plant's needs rootnotes ai light https://example.com/window.jpg rootnotes ai light-match --observed bright_indirect --required medium
Backup your data
rootnotes export -o "rootnotes-backup-$(date +%Y%m%d).json"
Scripting with JSON output
# Get all plant IDs rootnotes plants list --json | jq '.[].id' # Search and extract species rootnotes plants search "fern" --json | jq '.[].species'