Rewrite README install section as a 6-step walkthrough
Replace the terse install summary with a click-by-click guide that covers the full setup in both README.md and README.zh-CN.md: clone+pip, GCP service account, moving the key out of the repo, creating the sheet with header row, writing config.json, and a sanity check. Flag the zh-CN tab-name gotcha (工作表1 vs Sheet1) that causes HTTP 400 Unable to parse range. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
72
README.md
72
README.md
@@ -16,18 +16,78 @@ Intended to be invoked manually inside Claude Code today, and wired up to a What
|
||||
|
||||
## Install
|
||||
|
||||
Clone into your Claude Code skills directory:
|
||||
Follow the 6 steps below. Takes ~10 minutes.
|
||||
|
||||
### Step 1 — Clone the skill and install Python deps
|
||||
|
||||
```bash
|
||||
git clone https://git.deepknow.site/Knowit/AutoACCT.git ~/.claude/skills/bookkeeping
|
||||
pip install google-api-python-client google-auth
|
||||
```
|
||||
|
||||
Then follow [`scripts/setup.md`](scripts/setup.md) for the one-time setup:
|
||||
### Step 2 — Create a Google Cloud service account
|
||||
|
||||
- Python deps: `pip install google-api-python-client google-auth`
|
||||
- Create a GCP service account + download its JSON key
|
||||
- Create a Google Sheet, add 14 header columns, share with the service account email
|
||||
- `cp config.example.json config.json` and fill in `sheet_id` + `service_account_path`
|
||||
1. Open https://console.cloud.google.com/ and create a new project (e.g. `autoacct`).
|
||||
2. In the top search bar, search **Google Sheets API** → click the result → **Enable**.
|
||||
3. Left menu: **IAM & Admin → Service Accounts → + Create Service Account**
|
||||
- Name: `bookkeeping` (any name works)
|
||||
- Click **Create and Continue → Done** (skip the optional role step).
|
||||
4. Click the new service account → **Keys** tab → **Add Key → Create new key → JSON → Create**.
|
||||
A `.json` key file will download to your browser's Downloads folder.
|
||||
5. **Copy the service account's email** (looks like `bookkeeping@<project>.iam.gserviceaccount.com`) — you'll paste it in Step 4.
|
||||
|
||||
### Step 3 — Move the key file out of the repo
|
||||
|
||||
Never leave a service-account key inside the repo directory. Move it to `~/.config/gcp/`:
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.config/gcp
|
||||
mv ~/Downloads/<your-downloaded-file>.json ~/.config/gcp/bookkeeping-sa.json
|
||||
chmod 600 ~/.config/gcp/bookkeeping-sa.json
|
||||
```
|
||||
|
||||
### Step 4 — Create the Google Sheet
|
||||
|
||||
1. Open https://sheets.new (creates a fresh blank sheet).
|
||||
2. Give it a title (e.g. `AutoACCT Expenses`).
|
||||
3. **Note the tab name** at the bottom-left — default is `Sheet1` (English UI) or `工作表1` (Chinese UI). Write it down, you'll need the exact string in Step 5.
|
||||
4. Click cell **A1**, then paste this one line (the tabs split the headers across A–N automatically):
|
||||
```
|
||||
Date Merchant Category Amount Currency Amount (HKD) FX Rate FX Date Payment Method Line Items Raw OCR Note Receipt Logged At
|
||||
```
|
||||
5. Click **Share** (top right) → paste the service-account email from Step 2 → role **Editor** → **Send** (you can uncheck "Notify people").
|
||||
6. Copy the **Sheet ID** from the URL — it's the long string between `/d/` and `/edit`:
|
||||
`https://docs.google.com/spreadsheets/d/`**`1abc...xyz`**`/edit`
|
||||
|
||||
### Step 5 — Write config.json
|
||||
|
||||
```bash
|
||||
cd ~/.claude/skills/bookkeeping
|
||||
cp config.example.json config.json
|
||||
```
|
||||
|
||||
Open `config.json` in your editor and fill in **sheet_id** and **worksheet** with the values from Step 4:
|
||||
|
||||
```json
|
||||
{
|
||||
"sheet_id": "1abc...xyz",
|
||||
"worksheet": "Sheet1",
|
||||
"service_account_path": "~/.config/gcp/bookkeeping-sa.json",
|
||||
"hkd_fx_provider": "frankfurter"
|
||||
}
|
||||
```
|
||||
|
||||
> ⚠️ **Common pitfall**: if your Google Sheets UI is in Chinese, the default tab is named `工作表1` (not `Sheet1`). Put `"worksheet": "工作表1"` exactly. A mismatched tab name throws `HTTP 400: Unable to parse range`.
|
||||
|
||||
### Step 6 — Sanity check
|
||||
|
||||
```bash
|
||||
echo '{"date":"2026-04-20","merchant":"TEST","category":"Other","amount":1,"currency":"HKD","amount_hkd":1,"fx_rate":1,"fx_date":"2026-04-20"}' | python3 ~/.claude/skills/bookkeeping/scripts/append_row.py
|
||||
```
|
||||
|
||||
Success looks like: `OK 'Sheet1'!A2:N2` and a new row appears in the sheet. Delete the TEST row when you're done.
|
||||
|
||||
If you hit an error, see [`scripts/setup.md`](scripts/setup.md) for the longer reference.
|
||||
|
||||
## Use
|
||||
|
||||
|
||||
Reference in New Issue
Block a user