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 [email protected]: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