企业官网建设流程全解析

如何在 AI Agent 中使用 Midday CLI 的 --agent 模式获取结构化财务数据？

【免费下载链接】middayInvoicing, Time tracking, File reconciliation, Storage, Financial Overview & your own Assistant made for Freelancers项目地址: https://gitcode.com/GitHub_Trending/mi/midday

Midday CLI（npm 包名@midday-ai/cli）官方定位就是 "designed for humans and AI agents alike"。当你的 AI Agent、自动化脚本或 CI 任务需要读取 Midday 中的交易、发票和报表数据时，问题在于：默认的表格输出带颜色和进度动画，无法被程序解析。CLI 提供了一个全局标志--agent（Agent mode: JSON, no prompts, no spinners），配合 API Key 认证，可以拿到纯 JSON 输出并彻底避免交互式提示。本文完成一条完整路径：安装 CLI → 用 API Key 完成无头认证 → 用--agent拉取结构化财务数据 → 按 JSON 信封结构解析并判断成败。

一、安装 Midday CLI

README 给出两种安装方式：

# 一次性运行，不全局安装 npx @midday-ai/cli@latest # 或全局安装，之后直接调用 midday 命令 npm install -g @midday-ai/cli

在 Agent 环境中更常用全局安装，因为后续会多次调用midday子命令。

二、认证：Agent 环境下优先用 API Key

CLI 提供两条认证路径，Agent 场景要选对：

交互式 OAuth（适合人工首次登录）

midday auth login # 打开浏览器完成 OAuth midday auth login --no-browser # 只打印授权 URL，手动在浏览器打开

API Key（无头环境的主路径）

没有浏览器的 Agent 运行环境（服务器、容器）应使用 API Key，README 给出两种方式：

# 方式一：通过 stdin 传入，写入本地凭据存储 echo $MIDDAY_API_KEY | midday auth login --token-stdin # 方式二：直接设置环境变量，跳过 auth login MIDDAY_API_KEY=xxx midday transactions list

环境变量MIDDAY_API_KEY的文档说明是 "API key (skipauth login)"，即设置后无需再执行登录命令。

认证完成后用以下命令验证当前会话：

midday auth status

若未登录，auth status会提示未登录状态，而后续任何数据命令都会抛出认证错误（见第五节的排查部分）。

三、--agent 模式的输出规则

--agent是在根命令上注册的全局标志（见 CLI 入口），README 的 "Global Flags" 表中的说明是：--agent→ "Agent mode: JSON, no prompts, no spinners"。它带来的行为变化，均可在源码中核对：

1. 输出格式强制为 JSON。输出格式解析逻辑 中，只要flags.agent || flags.json为真就返回"json"，不再受终端是否为 TTY 影响。
2. 不显示进度动画和交互提示。--agent与--quiet、--json一样会关闭 UI 输出（见 shouldShowUI）。

成功输出的 JSON 信封

单对象命令（如transactions get、reports revenue）输出结构为{ "data": ... }；列表命令（如transactions list、invoices list）额外附带分页信息，结构来自 printJson / printJsonList：

{ "data": [], "pagination": { "has_more": false, "cursor": null, "page_size": 25 } }

以上是字段结构说明（字段名来自源码），data内是实际业务数据，数值会随你的账户内容变化。

错误输出

JSON 模式下错误写入stderr（stdout 保持干净，可直接被管道消费），结构为{ "error": { "code", "message" }, "data": null }，进程以退出码 1 结束（见 错误处理）。这对 Agent 很重要：可以同时检查退出码和 stderr 的 JSON 错误体来分支处理。

四、拉取结构化财务数据

以下命令均按 README 的 "Agent & MCP Integration" 示例采用--agent放在子命令之前的写法。

按日期范围列出交易

midday --agent transactions list --from 2026-01-01 --to 2026-03-31

transactions list支持完整的过滤参数（见 commands/transactions）：

分页：第一页返回的pagination.cursor配合has_more: true表示还有下一页，Agent 应循环执行midday --agent transactions list --cursor <上一页返回的 cursor>直到has_more为false。

发票数据

midday --agent invoices list --status unpaid

README 中还给出与jq组合的提取示例（--json与--agent都会产生 JSON 输出）：

midday invoices list --json | jq '.data[].invoiceNumber'

报表数据

报表命令支持--from、--to（YYYY-MM-DD）和--currency参数（见 commands/reports）：

midday --agent reports revenue --from 2026-01-01 --to 2026-03-31 midday --agent reports runway --currency USD midday --agent reports spending

可选的报表子命令包括revenue、profit、burn-rate、runway、expenses、spending。

通过 stdin 传入数据

Agent 生成的 JSON 也可以通过--stdin写回，README 示例：

cat invoice.json | midday invoices create --stdin

其中invoice.json是你自行准备的请求体文件。

五、验证与常见问题

判断调用是否成功：看退出码——成功为 0；失败为 1，且 stderr 是{ "error": { "code", "message" }, "data": null }结构的 JSON。Agent 侧可据此解析error.code做分支。

认证失败：未登录时错误消息为Not logged in. Run midday auth login to authenticate.（见 AuthRequiredError）。处理方式回到第二节：重新执行midday auth login --token-stdin或确认MIDDAY_API_KEY环境变量已导出。

请求排查：--debug全局标志会把详细的 HTTP 日志输出到 stderr，stdout 的 JSON 不受污染，适合 Agent 排障时附加使用。

端点覆盖：默认 API 地址为https://api.midday.ai（见 getApiUrl）。如需指向自部署或测试环境，可用环境变量MIDDAY_API_URL或全局标志--api-url <url>覆盖；OAuth 回调地址则可用MIDDAY_DASHBOARD_URL覆盖。

其他环境变量（README "Environment Variables" 表）：NO_COLOR可禁用彩色输出；MIDDAY_API_URL、MIDDAY_DASHBOARD_URL如上。

边界说明

--agent只改变输出形态（强制 JSON、关闭提示与动画），不改变任何请求的语义；它与--json在输出格式上等效，区别在于--agent是面向 Agent 的完整模式。认证凭据保存在本地凭据存储中，midday auth logout可清除；在多用户 Agent 环境里建议优先走MIDDAY_API_KEY环境变量，避免在机器上长期留存交互式登录的凭据。

【免费下载链接】middayInvoicing, Time tracking, File reconciliation, Storage, Financial Overview & your own Assistant made for Freelancers项目地址: https://gitcode.com/GitHub_Trending/mi/midday