convex-logs_skill

Overview

This skill checks and streams Convex deployment logs from the CLI to help you debug failed actions, validation errors, 401/500 responses, and timing information for queries, mutations, and actions. It lets you target dev or prod deployments, fetch recent history, and inspect deployment environment variables so you can correlate code, secrets, and runtime behavior. Use it directly from the app folder that contains the convex/ directory.

How this skill works

The skill runs convext CLI commands (npx convex logs / env) to stream log lines or fetch a history snapshot from the selected deployment. It shows which functions executed, their duration, and error messages. You can switch between dev (default) and prod with --prod, include successful runs, output raw JSONL, or target a specific deployment name. Env commands list or retrieve values set in the Convex deployment rather than local .env files.

When to use it

• Investigating user-reported errors from Convex actions (e.g. unauthorized, ArgumentValidationError, timeouts).
• Confirming which Convex deployment (dev vs prod) your app is using when behavior differs between environments.
• Seeing recent function executions, success/failure status, and execution durations for queries, mutations, and actions.
• Debugging missing or mismatched env vars (OA_INTERNAL_KEY, PUBLIC_API_URL) that cause 401s with external APIs.
• Fetching a finite set of recent entries instead of streaming when network or timeout issues occur.

Best practices

• Run commands from the app directory that contains convex/ (monorepos commonly use apps/web).
• Remember dev is the default; add --prod for production logs and env checks.
• Use --history N to fetch a finite number of entries and avoid streaming timeouts.
• Include --success when you need successful runs (defaults may show failures only).
• Use --deployment-name to target a specific deployment instance when multiple exist.

Example use cases

• Stream production logs to find a failing action returning 401: npx convex logs --prod --history 30 --success.
• Verify deployment env vars: npx convex env list --prod and npx convex env get OA_INTERNAL_KEY --prod.
• Quick snapshot of recent activity: npx convex logs --history 50 to inspect recent function timings and errors.
• Target a named deployment: npx convex logs --deployment-name dev:effervescent-anteater-82.
• Output raw log events for automated parsing: npx convex logs --jsonl --history 100.