Description

Use this skill when a user needs to install, authenticate, or operate the Just Calendar CLI against https://justcalendar.ai, including generating an agent to...

README (SKILL.md)

JustCalendar CLI Skill

Name: JustCalendar
Author: andredalmeida

Purpose

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

Backend-issued Google Drive access tokens from https://justcalendar.ai
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

Open https://justcalendar.ai
Login/connect Google Drive in the app
Click Connect to your Agent (OpenClaw button)
Click Generate New Token
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 \x3CYOUR_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: \x3Caccount-id>_\x3Ccalendar-id>.json
CLI local config: ~/.justcalendar-cli/config.json

Command Reference

Session / Auth

justcalendar login --token \x3CTOKEN> --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 \x3Cdate> \x3Cvalue> 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 \x3Ccalendar> \x3Cdate1> \x3Cvalue1> \x3Cdate2> \x3Cvalue2> ...
justcalendar data delete \x3Ccalendar> \x3Cdate1> \x3Cdate2> ...
justcalendar data get \x3Ccalendar> \x3Cdate1> \x3Cdate2> ...

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

Check connectivity:

justcalendar status

List calendars:

justcalendar calendars list

Apply desired calendar/data changes
Re-check specific days:

justcalendar data get "\x3CCalendar>" \x3Cdate1> \x3Cdate2> ...

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 \x3CNEW_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

Usage Guidance

This skill appears to describe and document a legitimate CLI and is coherent with its stated purpose, but take the following precautions before installing or using it: - Verify provenance: confirm the npm package name and publisher (npmjs.com) or the GitHub repository owner before running npm install -g or git clone. Malicious packages can be published under similar names. - Token handling: avoid pasting the token directly into a shell command if you can. Passing credentials on the command line can expose them in shell history and to other users on the same machine (ps). Prefer interactive login, environment variables, or storing the token in the CLI's config if the tool supports secure storage. If you must use the CLI argument, remove the command from shell history and rotate/revoke the token if it may have been exposed. - Least privilege: review what Google Drive permissions the Just Calendar web app requests when you connect it (ideally read/write limited to a justcalendar folder). Only grant permissions you understand and are comfortable with. - Review local config: the CLI writes ~/.justcalendar-cli/config.json and expects JustCalendar.ai files in Drive; inspect these files if you want to verify stored tokens or data before trusting them. - If you install globally, prefer verifying package integrity (checksums, signed releases) or installing in a virtual environment/container if you're unsure. If you want, I can: (1) show commands to install safely in a local project rather than globally, (2) suggest safer ways to provide the token (env var or interactive prompt) depending on what the CLI supports, or (3) help verify the npm/GitHub package metadata before you install.

Capability Analysis

Type: OpenClaw Skill Name: justcalendar Version: 1.0.2 The skill bundle provides comprehensive instructions for installing, authenticating, and operating the `justcalendar` Node.js CLI. All commands and instructions in SKILL.md are directly related to the stated purpose of managing calendar data via the CLI. It explicitly advises the agent to treat tokens as sensitive credentials. There are no indicators of prompt injection attempts to deviate from the stated purpose, no data exfiltration, no unauthorized execution, and no suspicious external domains or obfuscation. The installation methods (npm, git clone) are standard for CLI tools.

Capability Assessment

✓ Purpose & Capability

The name/description state a Node.js CLI that uses a backend token and Google Drive for calendar files; SKILL.md only instructs installing the CLI (npm or GitHub) and operating it against https://justcalendar.ai and Google Drive. There are no environment variables, unrelated binaries, or requests that don't match the stated purpose.

ℹ Instruction Scope

Instructions remain within the CLI/calendar scope, but they explicitly show passing the generated token on the command line (justcalendar login --token <TOKEN> --url ...). That is functional but has a security/privacy downside (shell history and process-list exposure). The doc also references local config (~/.justcalendar-cli/config.json) and Drive-backed files, which is expected for this tool.

✓ Install Mechanism

This is an instruction-only skill (no install spec). It suggests installing via npm or cloning a GitHub repo (SSH URL). Those are standard methods and no arbitrary/external archive downloads or obscure URLs are present. User should still verify package authenticity before global npm installs.

ℹ Credentials

No environment variables or unrelated credentials are requested. The single required secret is the one-time agent token generated by the web UI — appropriate for the stated workflow — but the provided usage pattern (token as a CLI argument) can expose the secret unnecessarily. The skill does not request additional unrelated keys or config paths.

✓ Persistence & Privilege

always is false and the skill is instruction-only; it doesn't request persistent platform privileges or modify other skills. The CLI itself will persist its own config under ~/.justcalendar-cli, which is expected for a CLI tool.

Version History

v1.0.2

- Added "Bulk-First Rule" section to require bulk commands (multi-date set/delete/get) by default for multi-day JustCalendar CLI operations. - Provided usage notes, examples, and exceptions for when to use bulk vs per-day commands. - Clarified that single-day commands remain unchanged. - No other changes to commands or skill behavior.

v1.0.1

- Skill name changed from justcalendar-cli to justcalendar - General references and examples updated to use justcalendar instead of justcalendar-cli - Description updated to reflect new skill name - No code or functionality changes detected

v1.0.0

Initial release of justcalendar-cli skill. - Provides guidance for installing and using the justcalendar-cli with Just Calendar via https://justcalendar.ai. - Covers authentication workflow (generating an agent token on the website and logging in via CLI). - Documents commands for calendar and day data management (add, list, rename, remove, set/get/delete data). - Explains accepted value formats per calendar type (signal-3, score, check, notes). - Includes troubleshooting tips for common authentication and permission errors. - Outlines prerequisites, installation steps, and recommended operating sequence.

Metadata

Slug justcalendar

Version 1.0.2

License —

All-time Installs 0

Active Installs 0

Total Versions 3

Frequently Asked Questions

What is JustCalendar?

Use this skill when a user needs to install, authenticate, or operate the Just Calendar CLI against https://justcalendar.ai, including generating an agent to... It is an AI Agent Skill for Claude Code / OpenClaw, with 315 downloads so far.

How do I install JustCalendar?

Run "/install justcalendar" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.

Is JustCalendar free?

Yes, JustCalendar is completely free (open-source). You can download, install and use it at no cost.

Which platforms does JustCalendar support?

JustCalendar is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).

Who created JustCalendar?

It is built and maintained by André Almeida (@andredalmeida); the current version is v1.0.2.

More Skills

JustCalendar