Hermes × Google Calendar CLI · local 8 min setup

Add Google Calendar to Hermes Agent Securely

Hermes Agent runs locally and shells out to tools through its skills system. To let it read your schedule and check availability the safe way, install the PortEden CLI, connect Google Calendar once, and wrap the CLI in a short Hermes skill. Your agent then reads events and free/busy through porteden calendar, which redacts attendee PII, enforces scope, and logs every call. No raw Google token touches the agent. Prefer MCP? PortEden runs as a remote MCP server too, covered at the end of this guide.

Hermes calls the PortEden CLI as a skill. PortEden is the local data firewall in front of Calendar.

What this unlocks

With the skill in place, your Hermes agent can list events, search by keyword or attendee, check free/busy, and (when you allow it) create and update meetings, all by running the PortEden CLI under the hood. Attendee PII is redacted before results reach the model, and every action is written to the PortEden audit trail with the command, the decision, and the response shape.

Compared with handing the agent a Calendar OAuth token, routing through the PortEden CLI gives you:

No raw credential in the agent: the Google token stays inside PortEden; the agent only runs a local command.
Attendee redaction so the model sees availability without full guest lists.
Confirm-before-write on create, update, delete, and respond, which notify other people.
Independent revocation and an audit trail you can hand to security review.

Prerequisites

Requirement	Details
Hermes Agent	Installed and runnable locally (the hermes command on your PATH)
PortEden CLI	Installed via Homebrew, the install script, or go install (Step 1)
Google account	With Google Calendar (personal or Workspace)
PortEden account	Free, created during login. No credit card.
Terminal	bash, zsh, or PowerShell

Two ways to connect

This guide leads with the PortEden CLI as a Hermes skill (fully local, nothing extra to host). Hermes also supports MCP servers, so you can wire PortEden in over MCP instead, see Alternative: connect via MCP. Both paths apply the same redaction, scope, and audit.

Step 1: Install the PortEden CLI

Pick whichever installer fits your machine.

Homebrew (macOS / Linux):

brew install porteden/tap/porteden

Install script:

curl -sSfL https://raw.githubusercontent.com/porteden/cli/main/install.sh | bash

Go:

go install github.com/porteden/cli/cmd/porteden@latest

Verify it is on your PATH:

porteden --help

Prefer not to install globally?

You can run any command one-off with npx @porteden/cli ... instead of a global porteden. The global install is smoother once Hermes is calling it on every request.

Step 2: Authenticate to PortEden

Log in once. The CLI opens your browser and stores a PortEden API key in your OS keyring, you can create a PortEden account in the same flow.

Start the browser login:

porteden auth login 
 
# Name the key so you can spot it later
porteden auth login --title "Hermes box"

Sign up (Google or email) or sign in. The key is stored in Keychain (macOS), Secret Service (Linux), or Credential Manager (Windows).

Confirm you are authenticated:

porteden auth status

Headless or CI machine?

Set PE_API_KEY=pe_your_key in the environment and the CLI uses it automatically, no browser step.

Step 3: Connect Google Calendar

Authorize Calendar scopes on your Google account. Google services share one connection in PortEden, so if you already connected Google for Gmail or Drive, this just adds Calendar.

Connect your Google account (grant Calendar access when prompted):

npx @porteden/cli connect google

Complete Google's consent screen. Read scope is enough to list events and check free/busy; grant write only if you want the agent to create or update events.

Verify the connection by listing your calendars:

porteden calendar calendars -jc 
porteden calendar events --today -jc

Note the calendar IDs from the first command; you need one to create events later.

Google Workspace accounts

If your Google account belongs to a Workspace, your admin may need to allow third-party OAuth before the connect step succeeds. If calendar commands return nothing, re-run the connect step to make sure Calendar scopes were granted.

Step 4: Add a Hermes skill that wraps the CLI

Hermes reads skills from ~/.hermes/skills/. A skill is a SKILL.md file with YAML frontmatter plus instructions the agent reads before it acts. Create one that documents the PortEden calendar commands.

Create the skill folder:

mkdir -p ~/.hermes/skills/porteden-calendar

Save this as ~/.hermes/skills/porteden-calendar/SKILL.md:

~/.hermes/skills/porteden-calendar/SKILL.md

--- 
name: porteden-calendar 
description: >- 
  Read Google Calendar events and check availability securely via the PortEden 
  CLI. Use when the user asks about their schedule, free/busy, or upcoming 
  meetings. Creating, updating, deleting, and responding require confirmation. 
metadata: 
  hermes: 
    tags: [calendar, scheduling, google, productivity] 
    category: productivity 
--- 
 
# PortEden Calendar
 
Use the `porteden calendar` command to read events and availability. Always 
pass the `-jc` flags (JSON + compact) for token-efficient output. 
 
## Read and search (safe, default)
 
- List calendars (for IDs): `porteden calendar calendars -jc` 
- Events today / tomorrow / this week: `porteden calendar events --today -jc` 
- Next N days: `porteden calendar events --days 14 -jc` 
- Search: `porteden calendar events -q "standup" --week -jc` 
- By attendee: `porteden calendar events -q "sync" --week --attendees "jane@acme.com" -jc` 
- By contact: `porteden calendar by-contact "jane@acme.com" -jc` 
- One event: `porteden calendar event <eventId> -jc` 
- Availability: `porteden calendar freebusy --week -jc` 
 
Times are RFC3339 UTC (e.g. `2026-02-01T10:00:00Z`). Get calendar IDs from the 
`calendars` command before creating events. 
 
## Write actions (confirm first)
 
Before `create`, `update`, `delete`, or `respond`, echo the event details 
(title, time, attendees) and wait for the user to confirm, these notify other 
attendees. 
 
- Create: `porteden calendar create --calendar <id> --summary "..." --from "..." --to "..."` 
- Respond: `porteden calendar respond <eventId> accepted` 
 
PortEden redacts attendee PII, enforces token scope, and logs every call.

Confirm Hermes picked up the skill:

hermes skills

porteden-calendar should appear in the list. If a chat session is already open, reload skills or restart it.

Make the description do the routing

Hermes chooses skills from their descriptions. Keep this one action-oriented ("schedule, free/busy, upcoming meetings") so calendar prompts route here.

Step 5: Verify and tighten

Verify end to end

Start a Hermes chat and ask the agent to use the skill:

hermes chat

What's on my calendar this week? Group by day.

When am I free for a 30-minute call on Thursday afternoon?

Review what happened

Run a command with verbose output to see the request/response (auth headers redacted), and check the full audit trail at my.porteden.com.

porteden -v calendar events --today -jc

Tighten the token (optional)

The token PortEden created defaults to calendar scope with redaction on. Adjust it from my.porteden.com under Access Tokens, or isolate accounts on the CLI side.

Common ways to narrow what the agent can reach

Tighten	How
Read-only	Keep write scopes off the token so the agent can read events and free/busy but not create or change them
Single calendar	Limit the token to one calendar instead of all of them
Isolate accounts	Run with PE_PROFILE=work (or --profile work) so a task touches only that account
Confirm before write	Treat create, update, delete, and respond as confirm-first in the skill
Revoke fast	porteden auth logout clears the keyring; revoke the token in PortEden to be sure

Alternative: connect via MCP

Hermes can also reach PortEden as a remote MCP server, configured in ~/.hermes/config.yaml. The CLI skill above keeps everything local; MCP reuses PortEden's hosted server and is handy if you already run other MCP servers in Hermes. Either path applies the same attendee redaction, scope, and audit.

Make sure Hermes has MCP support (it ships with the standard installer). If needed, add it:

cd ~/.hermes/hermes-agent 
uv pip install -e ".[mcp]"

Add the PortEden Calendar server to your config, served from the /calendar endpoint and bridged into Hermes with mcp-remote:

~/.hermes/config.yaml

mcp_servers: 
  porteden-calendar: 
    command: "npx" 
    args: ["-y", "mcp-remote", "https://mcp.porteden.com/calendar"]

Reload Hermes and confirm the server connected:

hermes mcp 
# or, inside a running chat session
/reload-mcp

The first tool call opens your browser to sign in to PortEden and authorize Calendar, the same consent as the CLI path.

Same firewall, your choice of transport

The MCP endpoint and the CLI skill both enforce PortEden redaction, scope, and the audit log. Use the skill for a fully local setup with no bridge; use MCP if you standardize on mcp_servers across agents.

Suggested prompts

Once the skill is live, try these in hermes chat:

Day plan

"Summarize my day. Flag any back-to-back meetings and any without an agenda."

Find time

"Find three 30-minute slots next week when I'm free between 9am and 4pm."

Prep

"List my meetings tomorrow with the other attendees and any linked docs in the description."

Schedule (confirm)

"Draft a 'Project sync' invite for Friday 10am with alice@acme.com. Show me the details; do not create it until I confirm."

Troubleshooting

NO_CALENDAR_SCOPE

Calendar commands return nothing or an access error

Symptoms

porteden calendar calendars -jc returns an empty list or an authorization error.
Events commands work for Gmail but not Calendar.

Checks

Re-run npx @porteden/cli connect google and grant Calendar scopes during consent.
Confirm you authorized the right Google account.
For Workspace accounts, ask your admin to allow third-party OAuth.

Debug prompt for the agent

Run `porteden calendar calendars -jc` and quote the output or error. Tell me whether Calendar scopes were granted in the last connect.

CLI_NOT_FOUND

hermes can run, but porteden is 'command not found'

Symptoms

The agent reports it cannot find the porteden binary.
porteden --help works in your shell but not when Hermes calls it.

Checks

Confirm the install: run porteden --help in the same shell Hermes launches from.
GUI-launched agents may not inherit your shell PATH. Install via Homebrew to a standard bin dir, or use an absolute path in the skill.
As a fallback, document npx @porteden/cli ... in the skill instead of the bare porteden command.

Debug prompt for the agent

Run `which porteden` (or `where porteden` on Windows) and tell me the path. Then try the same calendar command with the full absolute path.

INVALID_CALENDAR_ID

Creating an event fails with 'invalid calendar ID'

Symptoms

porteden calendar create returns an invalid calendar ID error.
The agent guessed a calendar ID.

Checks

List IDs first: porteden calendar calendars -jc, then pass --calendar <id>.
Use the exact ID string from the calendars output, not the calendar name.
Confirm the token has write scope if creating events.

Debug prompt for the agent

Run `porteden calendar calendars -jc` and quote the available IDs, then retry create with --calendar set to one of them.

SKILL_NOT_LOADED

Hermes does not use the skill

Symptoms

The agent answers from general knowledge instead of running porteden.
porteden-calendar is missing from hermes skills.

Checks

Confirm the file path is exactly ~/.hermes/skills/porteden-calendar/SKILL.md.
Validate the YAML frontmatter (name and description are required).
Reload skills or restart the chat session so Hermes re-scans the skills directory.
Make the description action-oriented so the agent selects it for scheduling prompts.

Debug prompt for the agent

List my available skills and tell me whether porteden-calendar is among them. If not, show any load error for the skills directory.

FAQ

Does the Hermes agent ever see my raw Google Calendar token?

No. The Google OAuth token lives inside PortEden, and the PortEden CLI stores only a PortEden API key in your OS keyring. Hermes shells out to the porteden command and gets back redacted, scoped results. The agent never holds a Calendar credential it could leak or escalate.

Are attendee details redacted?

Yes. PortEden redacts PII, including attendee identifiers, before results reach the model, and the -jc compact output also limits attendee lists. You can scope the token further so the agent sees availability without full guest lists.

Can the agent create or delete events?

Only if the token allows it. The recommended skill keeps the agent on read and free/busy, and treats create, update, delete, and respond as confirm-first actions, because they notify other attendees. Keep the token read-only until the workflow is proven.

I already connected Gmail. Do I need to connect Google again?

Google services share one connection in PortEden. If you connected Google for Gmail or Drive, Calendar rides the same grant once Calendar scopes are authorized. If calendar commands return nothing, re-run the connect step to add Calendar scopes.

Where is the audit log, and how do I revoke access?

Every porteden call is recorded in your PortEden audit trail at my.porteden.com. To cut the agent off, run porteden auth logout to clear the keyring on that machine, or revoke the token and disconnect Google from my.porteden.com. Revoking the PortEden token does not affect your human Google sign-in.

Next steps

Add Gmail to Hermes

Pair calendar with inbox triage on the same Google connection.

Add Google Drive to Hermes

Give the agent scoped file search and read.

PortEden CLI command reference

Every porteden calendar command, flag, and example.

PortEden CLI overview

Install, auth, credential storage, and output formats.

PortEden is a software provider, not a law firm, accounting firm, or compliance auditor, and nothing on this page is legal, compliance, tax, or other professional advice. PortEden does not issue compliance certifications, attestations, or audit opinions. This content is provided for general informational purposes only, on an as-is basis and without warranties of any kind, and may not reflect the most current laws, regulations, or your specific situation. Before acting on it, consult a qualified attorney, auditor, or compliance professional.