從終端機處理你的月結

只需設定一次 Ceum CLI，即可把一個月的追蹤工時與交易匯出成乾淨的 JSON 或 CSV，用熟悉的 Unix 工具重新整理，再把結果推回——全程不必離開你的 shell。

月結自有其節奏：加總工時、對帳金流、追討發票、歸檔數字。若你本就成天待在終端機裡，靠點擊各個畫面來完成這些事就是慢的做法。命令列客戶端（@ceum/cli）驅動的是與應用程式相同的操作——於是整套例行流程化為寥寥數道指令，下個月你能重新讀懂，也能交給 cron。

這份逐步導覽跟隨一項具體的工作——結清一個月——從空白的 shell 一路走到一份你能歸檔的報告。步驟 1 的設定只需付出一次；步驟 2 與 3 才是你真正會反覆執行的例行流程。

目標

把「又到月底了」變成一段簡短、可重複的序列：以機器可讀的格式匯出當月的追蹤工時與交易，整理成你需要的摘要，再把任何修正寫回——全都可寫成腳本，於是下個月只是一道指令。

1. 安裝並驗證——只需一次

CLI 是一個從 npm 安裝的小型執行檔：

$ npm install -g @ceum/cli      # installs the `ceum` command (Node.js 22+)

它以 MCP 權杖進行驗證，也就是驅動 MCP 整合的同一個權杖。在應用程式的設定 → 整合中產生一個，接著登入：

$ ceum auth login               # paste the token (starts with ceum_)
Signed in. 42 tools available under this token.

權杖會以 0600 權限存放在你的設定目錄中。若是不該碰觸磁碟的排程工作，改為透過環境變數傳入——最適合 cron 或 CI：

$ CEUM_TOKEN=ceum_… ceum invoices list

用具名的**設定檔（profile）**把不同的工作區分隔開（ceum auth add work，接著 ceum --profile work …）。指令面是依你的權杖能做什麼即時衍生而來的，因此 ceum --help 永遠精準顯示你可用的資源與動作。

2. 取回一個月的資料——以你能運用的格式

每一道 list 指令都是資源優先的（ceum <resource> <action>），並接受 -o 來選擇輸出格式。預設的 text 會排成便於閱讀的表格；而機器格式——json、csv、ndjson——則位元乾淨，適合用管線串接。

先從最關鍵的數字開始。time-entries aggregate 會加總符合某組篩選條件的追蹤工時，並可加以分組：

$ ceum time-entries aggregate \
    --start-date 2026-07-01 --end-date 2026-07-31 \
    --group-by project -o json

這會回傳當月的總秒數，以及依專案細分的明細。若要取出底層的資料列以放進試算表，可直接把它們列成 CSV——並用 --all 越過每次請求的分頁上限，把每一頁合併起來：

$ ceum time-entries list --start-date 2026-07-01 --end-date 2026-07-31 \
    --all -o csv > july-time.csv
$ ceum transactions list --all -o csv > july-transactions.csv

兩個小手法能讓輸出更精簡：--columns 精準挑選你想要的欄位，而儲存的**預設集（preset）**則保存一組篩選條件，免得你重打一遍：

$ ceum transactions list --columns date,desc,amount,type,client
$ ceum presets save transactions month --type expense    # save once
$ ceum transactions list --preset month -o json          # reuse (explicit flags win)

3. 整理它，再把修正推回

由於只有指令輸出會送往 stdout——提示、進度與錯誤全都送往 stderr——管線因此保持乾淨。這意味著 jq 之類的工具會完全如你所預期地運作：

$ ceum invoices list -o json | jq '.[] | select(.status=="overdue") | .invoiceNumber'
$ ceum time-entries aggregate --group-by tag -o json \
    | jq -r '.groups[] | [.key, .totalSeconds/3600] | @tsv'

管線是雙向的。當月結還包含把資料寫回時——比方說記錄一批支出——可從檔案或 stdin 把資料列餵給 bulk-create 指令；輸入會被自動辨識（JSON 陣列、單一物件、NDJSON 或 CSV），並切分成符合伺服器每次請求 50 筆的上限：

$ ceum transactions bulk-create --file july-expenses.ndjson
$ jq -c '.[]' corrections.json | ceum transactions bulk-create --stdin

至此整件事就是一份腳本了。結束代碼（exit code）編碼了失敗的類別（0 成功、2 用法、3 驗證、4 禁止、5 工具錯誤、6 網路、7 設定），因此 cron 工作能分辨網路瞬斷與權杖失效，並據以應對，而非默默失敗。

你最終會得到什麼

一場月結成了你執行的一份檔案，而非你逐一點擊的一個畫面：驗證一次，以 JSON 或 CSV 匯出當月資料，用你早已熟悉的工具重新整理，再把結果寫回——與應用程式執行的相同操作，接進你的 shell 與你的排程器。

偏好留在應用程式內、卻保有鍵盤驅動的速度？應用程式內建的命令列會在 Ceum 內的面板中執行相同的指令語法。而一旦數字匯出之後，看清時間究竟花到哪去與從追蹤的工作到已付款的發票便會接手匯出止步之處。

相關指南