Fresh Auth

Runtime prerequisites

• Install Node.js (18+) for scripts/office-cli.js and scripts/notion-query.js.
• Run commands from this skill folder or export explicit paths.

# Resolve skill location for common installers
export FRESH_AUTH_DIR="${HOME}/.agents/skills/fresh-auth"
[ -d "$FRESH_AUTH_DIR" ] || export FRESH_AUTH_DIR="${HOME}/.codex/skills/fresh-auth"

export OFFICE_CLI="${FRESH_AUTH_DIR}/scripts/office-cli.js"
export NOTION_CLI="${FRESH_AUTH_DIR}/scripts/notion-query.js"
export AUTH_SERVICE_URL="https://auth.freshhub.ai"

# Quick command discovery
[ -f "$OFFICE_CLI" ] && node "$OFFICE_CLI" status
[ -f "$NOTION_CLI" ] && node "$NOTION_CLI" status

Bundled scripts

• scripts/office-cli.js for Microsoft Graph-backed Drive, Mail, Calendar, and People actions.
• scripts/notion-query.js for Notion read/write workflows through auth service proxy.

Office + Graph: canonical flow

Follow this flow when granting access for Graph-backed tools.

# Register and create grants
node "$OFFICE_CLI" login
node "$OFFICE_CLI" request drive
node "$OFFICE_CLI" request mail
node "$OFFICE_CLI" request cal
node "$NOTION_CLI" request

# Verify active grants
node "$OFFICE_CLI" status
node "$NOTION_CLI" status

Agent-assisted verification handoff

When the agent runs login or request, the CLI may print a verification URL and code for human approval.

1. Agent runs the auth command and captures the exact verification output.
2. Agent sends the verification URL and code to the user (do not paraphrase).
3. Prefer sharing the prefilled URL format: https://auth.freshhub.ai/agent/verify?code=<CODE>
4. User opens the URL, confirms the code, clicks Verify Code, then manually clicks Approve on the next screen.
5. Agent waits for approval polling to complete, then continues with the requested task.

If approval fails, repeat the flow and confirm the user is signed into the intended Fresh Auth account before entering the code.

Command map: Office CLI

Drive / Graph storage

node "$OFFICE_CLI" drive list
node "$OFFICE_CLI" drive list "/Documents"
node "$OFFICE_CLI" drive search "Quarterly report"
node "$OFFICE_CLI" drive download <file-id> out.docx
node "$OFFICE_CLI" drive content <file-id>
node "$OFFICE_CLI" drive convert <file-id> --output=notes.md
node "$OFFICE_CLI" drive share <file-id> --type edit
node "$OFFICE_CLI" drive share <file-id> --anyone
node "$OFFICE_CLI" drive permissions <file-id>
node "$OFFICE_CLI" drive unshare <file-id> <permission-id>

Mail / Email

node "$OFFICE_CLI" mail inbox
node "$OFFICE_CLI" mail inbox --count 50
node "$OFFICE_CLI" mail unread
node "$OFFICE_CLI" mail search "team update"
node "$OFFICE_CLI" mail read <message-id>
node "$OFFICE_CLI" mail send --to "[email protected]" --subject "Brief" --body "Thanks for the update"
node "$OFFICE_CLI" mail send --to "brad" --subject "Quick check" --body "Approved" --yes
node "$OFFICE_CLI" mail reply <message-id> --body "Got it."
node "$OFFICE_CLI" mail reply-all <message-id> --body "Thanks everyone."

Calendar

node "$OFFICE_CLI" cal today
node "$OFFICE_CLI" cal tomorrow
node "$OFFICE_CLI" cal events --days 14
node "$OFFICE_CLI" cal events --full

People lookup (Graph contact helper)

node "$OFFICE_CLI" people "brad"
node "$OFFICE_CLI" people "brad" --verbose

Notion command map

node "$NOTION_CLI" login
node "$NOTION_CLI" request
node "$NOTION_CLI" status
node "$NOTION_CLI" me
node "$NOTION_CLI" find-db "my database"
node "$NOTION_CLI" search "my database"
node "$NOTION_CLI" get-db <database-id>
node "$NOTION_CLI" query-db <database-id>
node "$NOTION_CLI" get-page <page-id>
node "$NOTION_CLI" get-markdown <page-id>
node "$NOTION_CLI" create <database-id> "Title" -p "Status=In progress" -p "Priority=High"
node "$NOTION_CLI" update <page-id> -p "Status=Done"
node "$NOTION_CLI" set-body <page-id> -
node "$NOTION_CLI" append-body <page-id> -

Use find-db first when the database ID is unknown. It returns database id, title, and url so the ID can be copied directly into get-db, query-db, or create.

Notion backlog helper

# Optional: enable shortcuts for a specific Notion backlog database
export NOTION_BACKLOG_DB_ID="<database-id>"

node "$NOTION_CLI" backlog
node "$NOTION_CLI" backlog "In Progress"
node "$NOTION_CLI" create-backlog "New task"

Multi-tool patterns

• Run people first, then mail send --to <resolved email> for safer identity resolution.
• Pull a Notion task with search or query-db, then append context with append-body.
• Convert a meeting PDF in Drive to markdown with drive convert, then store notes in Notion via append-body.

Error handling

• no_agent_session: run node "$OFFICE_CLI" login.
• no_grant: run node "$OFFICE_CLI" request <drive|mail|cal>.
• token expired: run node "$OFFICE_CLI" status and follow the returned re-authorisation URL.
• no agent session (Notion): run node "$NOTION_CLI" login.
• no grant (Notion): run node "$NOTION_CLI" request.
• NOTION_BACKLOG_DB_ID missing: set variable or call generic query-db/create commands instead of backlog shortcuts.
• Microsoft account not linked: follow the URL output by Graph proxy responses.
• Notion account not linked: follow the Notion connect URL output by the CLI.

Public publication checks

• Keep proxy URL configurable by AUTH_SERVICE_URL.
• Do not embed API keys or session IDs in skill outputs.
• Keep all commands pointed at https://auth.freshhub.ai by default.
• Include both CLIs under this skill's scripts/ folder for self-contained installation.
• Mention both Microsoft 365 and Notion capabilities in onboarding docs because this is a unified user-facing access path.