Hermes × Google Drive CLI · local 8 min setup

Add Google Drive to Hermes Agent Securely

Hermes Agent runs locally and shells out to tools through its skills system. To let it find and read your Drive files the safe way, install the PortEden CLI, connect Google Drive once, and wrap the CLI in a short Hermes skill. Your agent then searches and reads files through porteden drive, which applies file-level rules, strips PII, 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 Drive.

What this unlocks

With the skill in place, your Hermes agent can search Drive, look up file metadata, fetch share/export links, and (when you allow it) organize files, all by running the PortEden CLI under the hood. File-level Drive rules and token scope decide what is visible, 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 Drive 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.
File-level rules: allow specific folders, block the rest.
Links only on download: no raw bytes streamed into the model context.
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 Drive (personal or Workspace)
Drive scope	The token needs driveAccessEnabled and a Google connection with Drive scopes (Step 3)
PortEden account	Free, created during login. No credit card.

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 Drive

Authorize Drive scopes on your Google account. If you already connected Google for Gmail or Calendar, this adds Drive access to the same connection.

Connect Drive:

npx @porteden/cli connect drive

Complete Google's consent screen for Drive scopes. The token must have driveAccessEnabled for Drive commands to work.

Verify the connection with a quick, redacted list:

porteden drive files -jc

File IDs are provider-prefixed (e.g. google:1BxiMVs0...). Pass them as-is.

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.

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 drive commands.

Create the skill folder:

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

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

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

--- 
name: porteden-drive 
description: >- 
  Search and read Google Drive files securely via the PortEden CLI. Use when the 
  user wants to find a document, list folder contents, or get file links. 
  Upload, move, rename, share, and delete require explicit confirmation. 
metadata: 
  hermes: 
    tags: [drive, files, google, productivity] 
    category: productivity 
--- 
 
# PortEden Drive
 
Use the `porteden drive` command to search and read Google Drive. Always pass 
the `-jc` flags (JSON + compact) for token-efficient output. 
 
## Read and search (safe, default)
 
- List files: `porteden drive files -jc` 
- Search by keyword: `porteden drive files -q "budget report" -jc` 
- Filter by folder: `porteden drive files --folder google:0B7_FOLDER_ID -jc` 
- Filter by type / name: `porteden drive files --mime-type application/pdf -jc` 
- File metadata: `porteden drive file google:FILEID -jc` 
- View / export links: `porteden drive download google:FILEID -jc` 
- Permissions: `porteden drive permissions google:FILEID -jc` 
 
File IDs are provider-prefixed (e.g. `google:1BxiMVs0...`). Pass them as-is. 
`download` returns URLs only, never binary content. Check `accessInfo` in 
responses to understand active token restrictions. 
 
## Write actions (confirm first)
 
Before `upload`, `mkdir`, `rename`, `move`, `share`, or `delete`, echo the 
file ID and intended change, then wait for the user to confirm. `delete` moves 
to Drive trash (reversible). 
 
PortEden enforces file-level rules and token scope, and logs every call.

Confirm Hermes picked up the skill:

hermes skills

porteden-drive 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 ("find a document, list folder contents") so file 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

Find my most recent PDF about the Q1 budget and give me the view link.

List the files in my 'Contracts' folder, newest first.

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 drive files -jc

Tighten the token (optional)

The token PortEden created applies Drive rules and scope. 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 search and read but not change files
Folder allowlist	Permit specific folders with Drive rules and block everything else
Isolate accounts	Run with PE_PROFILE=work (or --profile work) so a task touches only that account
Confirm before write	Treat upload, move, rename, share, and delete 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 file-level rules, redaction, 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 Drive server to your config, served from the /drive endpoint and bridged into Hermes with mcp-remote:

~/.hermes/config.yaml

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

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 Drive, the same consent as the CLI path.

Same firewall, your choice of transport

The MCP endpoint and the CLI skill both enforce PortEden's Drive rules, redaction, 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:

Find a file

"Find the latest deck mentioning 'onboarding' and give me the link. Do not change anything."

Folder audit

"List everything in my 'Shared with me' that was modified in the last 7 days."

Permissions check

"Show me who has access to the Q1 budget file. Flag anything shared publicly."

Organize (confirm)

"Propose a folder structure for my loose PDFs. Show the plan; do not move anything until I confirm."

Troubleshooting

DRIVE_NOT_ENABLED

Drive commands fail with an access or scope error

Symptoms

porteden drive files -jc returns an authorization or 'drive not enabled' error.
authWarnings appear in list responses.

Checks

Re-run npx @porteden/cli connect drive and complete Google's Drive consent.
Confirm the token has driveAccessEnabled in PortEden.
For Workspace accounts, ask your admin to allow third-party OAuth.

Debug prompt for the agent

Run `porteden drive files -jc` and quote the error or authWarnings. Tell me whether the token shows driveAccessEnabled in PortEden.

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 drive command with the full absolute path.

DRIVE_EMPTY

Search returns no files

Symptoms

porteden drive files -q "..." -jc returns nothing when you expect matches.
Only some files appear.

Checks

Broaden the query, or list without a filter: porteden drive files -jc.
Check the token's folder allowlist in PortEden; files outside allowed folders are hidden by design.
Use --shared-with-me for files others shared with you.

Debug prompt for the agent

Run `porteden drive files -jc` (no filter) and quote the count. Tell me the token's current folder allowlist.

SKILL_NOT_LOADED

Hermes does not use the skill

Symptoms

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

Checks

Confirm the file path is exactly ~/.hermes/skills/porteden-drive/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 file prompts.

Debug prompt for the agent

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

FAQ

Does the Hermes agent ever see my raw Google Drive 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 scoped, redacted results. The agent never holds a Drive credential it could leak or escalate.

Can I stop the agent from reaching certain folders or files?

Yes. PortEden applies file-level Drive rules and token scope, so you can allow specific folders and block the rest. The token's accessInfo describes the active restrictions, and every porteden drive call is filtered through them before the agent sees anything.

Can the agent delete or share my files?

Only if the token allows it. The recommended skill keeps the agent on search and read, and treats upload, move, rename, share, and delete as confirm-first actions. delete moves files to Drive trash (reversible) rather than hard-deleting. Keep the token read-only until the workflow is proven.

Does the agent download file contents?

porteden drive download returns view and export links only; no binary content is streamed. The agent works from metadata, search results, and links, which keeps large files and raw bytes out of the model context.

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 Drive from my.porteden.com. Revoking the PortEden token does not affect your human Google sign-in.

Next steps

Add Gmail to Hermes

Same CLI-as-skill pattern for inbox triage.

Add Google Calendar to Hermes

Scheduling and free/busy through the same CLI.

PortEden CLI command reference

Browse the full porteden command surface and flags.

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.