Aimer779 · webbrain-one · Aug 3, 2026
diff --git a/README.en-US.md b/README.en-US.md
@@ -0,0 +1,167 @@
+
+
+# ima-note-cli
+
+Thanks to the [Linux.do Community](https://linux.do/t/topic/1773167) for their support.
+
+`ima-note-cli` is a command-line tool for IMA OpenAPI that uses only the Python standard library. It supports searching, reading, writing, URL importing, and streaming uploads for Notes and Knowledge base. The official entry point is `ima`; `ima-note` is retained only as a legacy note-only compatibility entry point.
+
+## Features
+
+- Check credential configuration without displaying credential values;
+- Search, list, read, create, and append Notes;
+- Search/browse Knowledge base, add notes, web pages, remote files, and local files;
+- Securely read or export raw media;
+- Provide bounded pagination with `--all --max-pages` for list/search operations;
+- Provide `--on-conflict error|rename` for file conflicts;
+- Provide `--download-timeout` and `--upload-timeout` for remote downloads and COS uploads;
+- Provide stable single-document JSON, per-item stage/summary, and exit code 9 partial semantics.
+
+## CLI and Skill Distribution
+
+The repository contains only one active agent skill: [skills/ima-note-cli](skills/ima-note-cli/SKILL.md). Its distribution is `repository-only`.
+
+`uv tool install` only installs the Python CLI; it does not install the agent skill. To use the skill, please copy or link `skills/ima-note-cli` separately from a source checkout. The wheel does not include `skills/`, `third_party/`, or archived CJS. For full details, see the [skill distribution policy](docs/SKILL_DISTRIBUTION_POLICY.md).
+
+## Install CLI
+
+Install from GitHub:
+
+```bash
+uv tool install git+https://github.com/Aimer779/ima-note-cli
+ima --help
+```
+
+Update or uninstall:
+
+```bash
+uv tool install --reinstall git+https://github.com/Aimer779/ima-note-cli
+uv tool uninstall ima-note-cli
+```
+
+Local development:
+
+```bash
+git clone https://github.com/Aimer779/ima-note-cli
+cd ima-note-cli
+uv venv
+uv pip install -e .
+uv run python -m ima_note_cli --help
+```
+
+## Credentials
+
+Requires `IMA_OPENAPI_CLIENTID` and `IMA_OPENAPI_APIKEY`. The CLI resolves each field independently with the following priority:
+
+1. Process environment variables;
+2. `.env` in the current working directory;
+3. `~/.config/ima/client_id` and `~/.config/ima/api_key`.
+
+System environment variables are recommended after global installation, as `.env` is only read from the current directory. To check, use:
+
+```bash
+ima auth
+ima auth --json
+```
+
+`ima auth` only shows the configuration status and source, not the values. Do not put real credentials in command-line arguments, logs, or issue reports.
+
+PowerShell current session example:
+
+```powershell
+$env:IMA_OPENAPI_CLIENTID="your_client_id"
+$env:IMA_OPENAPI_APIKEY="your_api_key"
+```
+
+macOS/Linux current session example:
+
+```bash
+export IMA_OPENAPI_CLIENTID="your_client_id"
+export IMA_OPENAPI_APIKEY="your_api_key"
+```
+
+On Windows, if you encounter terminal encoding errors, set `PYTHONUTF8=1` and `PYTHONIOENCODING=utf-8` and retry.
+
+## Common Workflows
+
+Notes:
+
+```bash
+ima note search "meeting"
+ima note folders
+ima note list --folder-id "folder_id" --all --max-pages 20
+ima note get "note_id"
+ima note create --title "Title" --content "Body"
+ima note append "note_id" --file update.md
+```
+
+`note_id` is the canonical identifier. `ima kb add-note --doc-id` and JSON `doc_id` are only deprecated compatibility features; the official usage is `--note-id`/`note_id`.
+
+Knowledge:
+
+```bash
+ima kb search-base "project"
+ima kb show-base --kb-id "kb_id"
+ima kb browse --kb-id "kb_id" --all --max-pages 20
+ima kb search "schedule" --kb-id "kb_id"
+ima kb addable
+ima kb add-note --kb-id "kb_id" --note-id "note_id" --title "Title"
+ima kb add-url --kb-id "kb_id" --url "https://example.com/article" --download-timeout 30 --upload-timeout 60
+ima kb add-file --kb-id "kb_id" --file report.pdf --file notes.md --on-conflict error --upload-timeout 60
+ima kb media-info --media-id "media_id"
+ima kb read --media-id "media_id"
+ima kb export --media-id "media_id" --output original.bin
+```
+
+For all exact arguments, defaults, choices, and required status, see the parser-generated [CLI reference](docs/CLI_REFERENCE.md), or run `ima ... --help`.
+
+## Security Boundaries
+
+Notes are validated for UTF-8 before writing, and local paths, data URIs, and non-HTTP(S) image references in Markdown/HTML are removed. Confirm targets before writing and uploading.
+
+`add-url` implements SSRF protection for user URLs: restricts scheme/port, rejects userinfo/IP/localhost/non-public DNS, validates redirects hop-by-hop and binds to verified public IPs; does not send IMA/COS credentials, cookies, or environment proxies. HTML/WeChat pages use web import; supported remote files undergo bounded download before entering the same upload gate as local files.
+
+Uploads use 64 KiB streaming reads, fixed Content-Length, pre- and post-file identity checks, and official COS host validation. The default conflict policy is to fail; only explicit `--on-conflict rename` triggers automatic renaming.
+
+`media-info` outputs only sanitized metadata. `read` only reads explicit text MIME types up to 4 MiB; use `export` for binaries. Export is limited to 200 MiB, defaults to not overwriting, and `--force` still uses atomic replacement via a temporary file. Full signed URLs, temporary headers, IMA credentials, and COS secrets should not appear in the output.
+
+## JSON and Exit Codes
+
+Add `--json` at the end of a command to get a stdout JSON document; JSON failure keeps stderr empty. Common fields include `schema_version`, `ok`, `status`, `command`, and `warnings`; batch results also include `summary`, `results`, and per-item `stage`.
+
+| Exit Code | Meaning |
+| --- | --- |
+| 0 | success/empty |
+| 2 | input error |
+| 3 | configuration error |
+| 4 | network error |
+| 5 | IMA business error |
+| 6 | protocol error |
+| 7 | original-content/local I/O error |
+| 8 | upload error |
+| 9 | partial or itemized batch failure |
+| 70 | internal error |
+| 130 | interrupted |
+
+## Development and Verification
+
+```bash
+uv run python -m unittest discover -s tests -v
+uv run python tools/render_cli_reference.py --check
+uv run python tools/check_repository_docs.py
+uv run python -m compileall -q src tests tools
+```
+
+The project adds no new production dependencies. Repository consistency checks run offline, reading no real credentials or accessing the network.
+
+## Documentation
+
+- [CLI reference (generated)](docs/CLI_REFERENCE.md)
+- [IMA OpenAPI 1.1.7 Sole Contract](docs/IMA_OPENAPI_CONTRACT_1_1_7.md)
+- [Skill distribution policy](docs/SKILL_DISTRIBUTION_POLICY.md)
+- [Skill migration matrix](docs/SKILL_MIGRATION_1_1_7.md)
+- [Third-party notices](THIRD_PARTY_NOTICES.md)
+
+## Third-party provenance
+
+This project references `ima-skills` 1.1.7. Original bytes, SHA-256, source, and MIT-0 evidence are preserved in [third_party/ima-skills/1.1.7](third_party/ima-skills/1.1.7). This archive is evidence-only and is not an active skill or runtime. MIT-0 applies only to this upstream archive; the project itself independently declares MIT, with the project root LICENSE to be completed in phase 7.