TidyCal CLI

TidyCal's REST API provides a handful of endpoints which can be used to get information about your account and bookings. It uses conventional OAuth 2.0 protocol for authentication.

Personal Access Token

Create a personal access token at https://tidycal.com/integrations/oauth. Once created, it can be used to authenticate requests by passing it in the Authorization header.

Authorization: Bearer {TOKEN}

OAuth 2.0 Client

If you're building a custom integration to TidyCal which requires users to authenticate in order to get access tokens to make API requests on their behalf, you'll need to create an OAuth 2.0 client. This is easy to do from the "OAuth Apps" settings page found here https://tidycal.com/integrations/oauth

Using the authorization_code grant type to authenticate users using OAuth 2.0 to retrieve an access token is fairly conventional, more information on that process can be found here: https://www.oauth.com/oauth2-servers/server-side-apps/authorization-code/

• Authorization URL: https://tidycal.com/oauth/authorize
• Access Token URL: https://tidycal.com/oauth/token

Learn more at Tidycal.

Created by @cathrynlavery (Cathryn Lavery).

Quick Start

1. Install

See Install above.

2. Set Up Credentials

Get your access token from your API provider's developer portal, then store it:

tidycal-pp-cli auth set-token YOUR_TOKEN_HERE

Or set it via environment variable:

export TIDYCAL_API_TOKEN="your-token-here"

3. Verify Setup

tidycal-pp-cli doctor

This checks your configuration and credentials.

4. Try Your First Command

tidycal-pp-cli booking-types list

Unique Features

These capabilities aren't available in any other tool for this API.

Agentic scheduling

• brief — Produce a contact-aware schedule brief for a day or date range.

  Use this before drafting prep notes or deciding whether a booking needs attention.

  tidycal-pp-cli brief --date today --format json
  

• triage — Identify booking problems such as missing meeting URLs, duplicate contacts, off-hours bookings, cancelled bookings, and incomplete contact data.

  Use this to decide which bookings require operator review.

  tidycal-pp-cli triage --from today --to +7d --format json
  

• propose-times — Fetch available TidyCal timeslots for a booking type and rank a paste-ready shortlist by date window, timezone, preference, and weekend policy.

  Use this when proposing meeting options in chat or email.

  tidycal-pp-cli propose-times 123 --from today --to +14d --count 3 --format json
  

• followups — Create an AI-ready follow-up queue from recent bookings without sending messages or notifications.

  Use this to prepare follow-up tasks after recent meetings.

  tidycal-pp-cli followups --from -7d --to today --format json
  

• assisted-book — Book on behalf of a contact through an inspectable dry-run and explicit confirmation gate.

  Use this only when the operator has approved the booking details.

  tidycal-pp-cli assisted-book 123 --name Ada --email ada@example.com --slot 2026-06-02T15:00:00Z --dry-run --format json
  

Usage

Run tidycal-pp-cli --help for the full command reference and flag list.

Commands

booking-types

Manage booking types

• tidycal-pp-cli booking-types create - Create a new booking type.
• tidycal-pp-cli booking-types list - Get a list of booking types.

bookings

Manage bookings

• tidycal-pp-cli bookings get - Get a booking by ID.
• tidycal-pp-cli bookings list - Get a list of bookings.

contacts

Manage contacts

• tidycal-pp-cli contacts create - Create a new contact.
• tidycal-pp-cli contacts list - Get a list of contacts.

me

Manage me

• tidycal-pp-cli me - Get account details.

teams

Manage teams

• tidycal-pp-cli teams get - Get details of a specific team.
• tidycal-pp-cli teams list - Get a list of teams the authenticated user has access to.

Output Formats

# Human-readable table (default in terminal, JSON when piped)
tidycal-pp-cli booking-types list

# JSON for scripting and agents
tidycal-pp-cli booking-types list --json

# Filter to specific fields
tidycal-pp-cli booking-types list --json --select id,name,status

# Dry run — show the request without sending
tidycal-pp-cli booking-types list --dry-run

# Agent mode — JSON + compact + no prompts in one flag
tidycal-pp-cli booking-types list --agent

Agent Usage

This CLI is designed for AI agent consumption:

• Non-interactive - never prompts, every input is a flag
• Pipeable - --json output to stdout, errors to stderr
• Filterable - --select id,name returns only fields you need
• Previewable - --dry-run shows the request without sending
• Explicit retries - add --idempotent to create retries and --ignore-missing to delete retries when a no-op success is acceptable
• Confirmable - --yes for explicit confirmation of destructive actions
• Piped input - write commands can accept structured input when their help lists --stdin
• Offline-friendly - sync/search commands can use the local SQLite store when available
• Agent-safe by default - no colors or formatting unless --human-friendly is set

Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.

Health Check

tidycal-pp-cli doctor

Verifies configuration, credentials, and connectivity to the API.

Configuration

Config file: ~/.config/tidycal-pp-cli/config.toml

Static request headers can be configured under headers; per-command header overrides take precedence.

Environment variables:

Name	Kind	Required	Description
TIDYCAL_API_TOKEN	per_call	No	Set to your API credential.
TIDYCAL_BEARER_AUTH	per_call	No	Set to your API credential.

agentcookie (optional)

If you use agentcookie to sync secrets across machines, this CLI auto-adopts agentcookie-managed credentials with no extra setup. When the daemon writes to this CLI's config, tidycal-pp-cli doctor reports agentcookie: detected and auth-status labels the source as agentcookie. Skip this section if you don't use agentcookie - the CLI works the same as any other.

Troubleshooting

Authentication errors (exit code 4)

• Run tidycal-pp-cli doctor to check credentials
• Verify the environment variable is set: echo $TIDYCAL_API_TOKEN Not found errors (exit code 3)
• Check the resource ID is correct
• Run the list command to see available items

---

Generated by CLI Printing Press