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. 1. Backend-issued Google Drive access tokens from INLINECODE1
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 INLINECODE2
• 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 INLINECODE3
• INLINECODE4
• Access to INLINECODE5
• A Google Drive-connected session in the web app (required to generate token and use Drive-backed operations)

Installation

Global install from npm:

CODEBLOCK0

From local project path:

CODEBLOCK1

If installing from GitHub:

CODEBLOCK2

Authentication Workflow (Web -> CLI)

Step 1: Generate token on website

1. 1. Open INLINECODE6
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

CODEBLOCK3

Verify:

CODEBLOCK4

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 INLINECODE7
• Data is stored under JustCalendar.ai folder in Google Drive
• Main config file: INLINECODE9
• Calendar data files: INLINECODE10
• CLI local config: INLINECODE11

Command Reference

Session / Auth

CODEBLOCK5

Calendars

CODEBLOCK6

Calendar type options:

• - INLINECODE12
• INLINECODE13
• INLINECODE14
• INLINECODE15

Color options:

• - green, red, orange, yellow, cyan, INLINECODE21

Score display options (for score type):

• - number, heatmap, INLINECODE25

Day Data - Set

Single set:

CODEBLOCK7

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

CODEBLOCK8

Day Data - Delete

Single delete:

CODEBLOCK9

Bulk delete (multiple dates in one call):

CODEBLOCK10

Day Data - Get

Single get:

CODEBLOCK11

Bulk get (multiple dates in one call):

CODEBLOCK12

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:

• - INLINECODE27
• INLINECODE28
• INLINECODE29

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:

CODEBLOCK13

Month delete in one data delete call:

CODEBLOCK14

Multi-day verification in one data get call:

CODEBLOCK15

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:

• - INLINECODE35
• INLINECODE36
• INLINECODE37
• INLINECODE38
• INLINECODE39 / unset / none (removes value)

score

Accepted values:

• - Integers from -1 to INLINECODE44
• INLINECODE45 means unset/remove

check

Accepted truthy values:

• - true, 1, yes, on, INLINECODE51

Falsy/unset values:

• - false, 0, no, off, unchecked, clear, unset, INLINECODE59

notes

Accepted:

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

Unset:

• - Empty/blank value (or use data delete)

Recommended Operating Sequence

1. 1. Check connectivity:

CODEBLOCK16

1. 2. List calendars:

CODEBLOCK17

1. 3. Apply desired calendar/data changes

1. 4. Re-check specific days:

CODEBLOCK18

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:

CODEBLOCK19

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 INLINECODE69
• Ensure calendar date is valid (for example, 2026-02-30 is invalid)

Ambiguous calendar name

• - Use calendar id from:

CODEBLOCK20

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

CODEBLOCK21