porteden docs-logger

Append log lines to daily Google Docs — one document per day, auto-created inside a PE_Logs folder. Works like a cloud-native .txt log file that agents can write to from anywhere. Use -jc flags for AI-optimized output.

If porteden is not installed: brew install porteden/tap/porteden (or go install github.com/porteden/cli/cmd/porteden@latest).

Setup

1. Authenticate (once)

• Browser login (recommended): porteden auth login — opens browser, credentials stored in system keyring
• Direct token: porteden auth login --token \x3Ckey> — stored in system keyring
• Verify: porteden auth status
• If PE_API_KEY is set in the environment, the CLI uses it automatically (no login needed).
• Drive access requires a token with driveAccessEnabled: true and a connected Google account with Drive scopes.

2. Set the log folder (one-time)

If PE_LOG_FOLDER is already set, skip to the logging workflow — the folder is configured.

If PE_LOG_FOLDER is not set, search for an existing PE_Logs folder:

porteden drive files --name "PE_Logs" --mime-type application/vnd.google-apps.folder -jc

If found, copy the id field and set it:

export PE_LOG_FOLDER="google:0B7_FOLDER_ID..."

If not found, create the folder:

porteden drive mkdir --name "PE_Logs" -jc

Copy the id from the response and set it:

export PE_LOG_FOLDER="google:0B7_FOLDER_ID..."

To persist across sessions, add to your shell profile (~/.bashrc, ~/.zshrc) or .env file. Once set, this step does not need to be repeated.

Logging workflow (per run)

Each run appends log lines to today's document. Follow these two steps every time you need to log.

Step 1. Find or create today's doc

Search for a doc named with today's date (YYYY-MM-DD) inside the log folder:

porteden drive files --name "2025-01-15" --folder $PE_LOG_FOLDER --mime-type application/vnd.google-apps.document -jc

If found, use the id from the result as the doc ID for step 2.

If not found, create today's doc:

porteden docs create --name "2025-01-15" --folder $PE_LOG_FOLDER -jc

Use the id from the response as the doc ID for step 2.

Step 2. Append the log line

porteden docs edit \x3CDOC_ID> --append "[09:30:00Z] deploy | production | v2.4.1 released | success"

Each --append adds text at the end of the document, preserving all previous entries.

Multiple lines in one call:

porteden docs edit \x3CDOC_ID> --append "[09:30:00Z] deploy | production | v2.4.1 released | success
[09:31:12Z] healthcheck | production | all endpoints healthy | success"

Log format examples

Use a consistent line format. Recommended patterns:

Timestamped event: [HH:MM:SSZ] event | source | details | status

Audit entry: [HH:MM:SSZ] actor | action | resource | result

Error line: [HH:MM:SSZ] ERROR | service | message

Task result: [HH:MM:SSZ] task | agent | input → output | duration

The date is already in the document name — log lines only need the time component.

Reading logs

Read today's log:

porteden docs read \x3CDOC_ID>

List all log documents in the folder:

porteden drive files --folder $PE_LOG_FOLDER -jc

Read a specific day's log:

porteden drive files --name "2025-01-10" --folder $PE_LOG_FOLDER --mime-type application/vnd.google-apps.document -jc

Then read by its ID:

porteden docs read \x3CDOC_ID>

Best practices

1. Always use --append — never overwrite log docs. Append-only preserves the full audit trail.
2. Use ISO 8601 date for doc names (YYYY-MM-DD) — ensures chronological sort and unique daily docs.
3. Include only the time in log lines — the date is in the document name, no need to repeat it.
4. Batch multiple log lines in one --append — separate lines with \ to reduce API calls.
5. Use a consistent delimiter — pipe | keeps fields scannable. Avoid commas in free-text fields.
6. Search before creating — always check if today's doc exists before creating a new one to avoid duplicates.
7. Use -jc on drive/read calls — compact JSON output minimizes tokens for AI agents.

Notes

• Credentials persist in the system keyring after login. No repeated auth needed.
• Set PE_PROFILE=work to avoid repeating --profile.
• -jc is shorthand for --json --compact: strips noise, limits fields, reduces tokens for AI agents.
• File IDs are always provider-prefixed (e.g., google:1BxiMVs0XRA5...). Pass them as-is.
• porteden docs read returns plain text by default.
• --append adds text at the end of the document. Each call appends — it does not replace.
• accessInfo in responses describes active token restrictions.
• PE_LOG_FOLDER is the only env var specific to this skill. Store it alongside PE_API_KEY.
• Environment variables: PE_API_KEY, PE_PROFILE, PE_LOG_FOLDER, PE_FORMAT, PE_COLOR, PE_VERBOSE.