JustCalendar CLI Skill

Purpose

This skill provides complete operational guidance for justcalendar, a Node.js CLI that manages Just Calendar data in Google Drive through:

1. Backend-issued Google Drive access tokens from https://justcalendar.ai
2. Direct Google Drive API reads/writes for calendar data files

Use this skill for setup, login, troubleshooting, and day-to-day CLI operations.

When To Use This Skill

Use this skill when user asks to:

• Install or update justcalendar
• Login with a token generated in Just Calendar web interface
• Add, list, rename, remove, or select calendars
• Set/get/delete day values from calendars
• Run bulk data operations from terminal
• Troubleshoot token/auth/permission errors

Prerequisites

• Node.js >=18
• npm
• Access to https://justcalendar.ai
• A Google Drive-connected session in the web app (required to generate token and use Drive-backed operations)

Installation

Global install from npm:

npm install -g justcalendar
justcalendar --help

From local project path:

cd ~/justcalendar-cli
npm install
npm install -g .
justcalendar --help

If installing from GitHub:

git clone git@github.com:AndredAlmeida/justcalendar-cli.git
cd justcalendar-cli
npm install
npm install -g .
justcalendar --help

Authentication Workflow (Web -> CLI)

Step 1: Generate token on website

1. Open https://justcalendar.ai
2. Login/connect Google Drive in the app
3. Click Connect to your Agent (OpenClaw button)
4. Click Generate New Token
5. Copy token immediately

Important:

• Token is shown once
• Generating a new token invalidates the previous token
• If popup says token already exists but hidden, generate a new one to get a visible token

Step 2: Login CLI with token

justcalendar login --token <YOUR_TOKEN> --url https://justcalendar.ai

Verify:

justcalendar status

Expected status includes backend URL, token state, and current calendars (if authenticated).

CLI Data Model Notes

• Calendar selector can be calendar id or calendar name
• Date format is strict YYYY-MM-DD
• Data is stored under JustCalendar.ai folder in Google Drive
• Main config file: justcalendar.json
• Calendar data files: <account-id>_<calendar-id>.json
• CLI local config: ~/.justcalendar-cli/config.json

Command Reference

Session / Auth

justcalendar login --token <TOKEN> --url https://justcalendar.ai
justcalendar logout
justcalendar status

Calendars

justcalendar calendars list
justcalendar calendars add "Workout" --type score --color red --display heatmap --pinned
justcalendar calendars rename "Workout" "Workout Intensity"
justcalendar calendars remove "Workout Intensity"
justcalendar calendars select "Energy Tracker"

Calendar type options:

• signal-3
• score
• check
• notes

Color options:

• green, red, orange, yellow, cyan, blue

Score display options (for score type):

• number, heatmap, number-heatmap

Day Data - Set

Single set:

justcalendar data set "Energy Tracker" 2026-03-01 green

Bulk set (multiple <date> <value> pairs in one call):

justcalendar data set "Energy Tracker" 2026-03-01 green 2026-03-02 yellow 2026-03-03 red

Day Data - Delete

Single delete:

justcalendar data delete "TODOs" 2026-03-01

Bulk delete (multiple dates in one call):

justcalendar data delete "TODOs" 2026-03-01 2026-03-02 2026-03-03

Day Data - Get

Single get:

justcalendar data get "Sleep" 2026-03-01

Bulk get (multiple dates in one call):

justcalendar data get "Sleep" 2026-03-01 2026-03-02 2026-03-03

Bulk-First Rule (Multi-Day Operations)

When handling more than one date, prefer one bulk command over looping per-day commands.

Use these bulk patterns by default:

• justcalendar data set <calendar> <date1> <value1> <date2> <value2> ...
• justcalendar data delete <calendar> <date1> <date2> ...
• justcalendar data get <calendar> <date1> <date2> ...

Use bulk whenever request scope is more than one day, including:

• Date ranges
• Whole week or whole month operations
• Backfills
• Batch fixes

Fall back to per-day commands only when:

• Bulk command length would exceed shell/OS command length limits
• Per-day retries are required for a failed subset

Single-day requests stay unchanged: use the existing single-date command forms.

Bulk Examples

Week update in one data set call:

justcalendar data set "Energy Tracker" \
  2026-03-02 green 2026-03-03 yellow 2026-03-04 red \
  2026-03-05 green 2026-03-06 green 2026-03-07 yellow 2026-03-08 green

Month delete in one data delete call:

justcalendar data delete "TODOs" \
  2026-02-01 2026-02-02 2026-02-03 2026-02-04 2026-02-05 2026-02-06 2026-02-07 \
  2026-02-08 2026-02-09 2026-02-10 2026-02-11 2026-02-12 2026-02-13 2026-02-14 \
  2026-02-15 2026-02-16 2026-02-17 2026-02-18 2026-02-19 2026-02-20 2026-02-21 \
  2026-02-22 2026-02-23 2026-02-24 2026-02-25 2026-02-26 2026-02-27 2026-02-28

Multi-day verification in one data get call:

justcalendar data get "Sleep" \
  2026-03-01 2026-03-02 2026-03-03 2026-03-04 2026-03-05 2026-03-06 2026-03-07

Performance + consistency note:

• Bulk commands reduce CLI/API overhead and reduce partial-write risk versus many per-day calls.

Value Rules By Calendar Type

signal-3

Accepted values for data set:

• red
• yellow
• green
• x
• clear / unset / none (removes value)

score

Accepted values:

• Integers from -1 to 10
• -1 means unset/remove

check

Accepted truthy values:

• true, 1, yes, on, checked

Falsy/unset values:

• false, 0, no, off, unchecked, clear, unset, none

notes

Accepted:

• Any non-empty text string (quote if spaces)

Unset:

• Empty/blank value (or use data delete)

Recommended Operating Sequence

1. Check connectivity:

justcalendar status

2. List calendars:

justcalendar calendars list

3. Apply desired calendar/data changes

4. Re-check specific days:

justcalendar data get "<Calendar>" <date1> <date2> ...

Troubleshooting

Not logged in. Run: justcalendar login ...

• Run login again with valid token

invalid_agent_token / missing_agent_token

• Generate new token in web app popup
• Re-run:

justcalendar login --token <NEW_TOKEN> --url https://justcalendar.ai

missing_drive_scope

• In web app, reconnect Google Drive and approve Drive access (drive.file)
• Generate new agent token
• Login again in CLI

token_refresh_failed / not_connected

• Drive session on server is expired/disconnected
• Reconnect Google Drive on website, generate new token, and login again

Date format errors

• Use exact YYYY-MM-DD
• Ensure calendar date is valid (for example, 2026-02-30 is invalid)

Ambiguous calendar name

• Use calendar id from:

justcalendar calendars list

Safety / Behavior Notes

• calendars remove is destructive for that calendar and its associated data file
• Bulk data set/data delete operations issue a single final write per command invocation
• Keep agent tokens secret; treat like credentials
• Rotate token by generating a new one (old token is invalidated)

Quick Start Example

justcalendar login --token jca_... --url https://justcalendar.ai
justcalendar calendars list
justcalendar calendars add "Hydration" --type check --color cyan
justcalendar data set "Hydration" 2026-03-01 true 2026-03-02 true 2026-03-03 false
justcalendar data get "Hydration" 2026-03-01 2026-03-02 2026-03-03