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/
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