diff --git a/.github/workflows/config-test.yml b/.github/workflows/config-test.yml index 4d67eab..3478808 100644 --- a/.github/workflows/config-test.yml +++ b/.github/workflows/config-test.yml @@ -29,6 +29,9 @@ jobs: - name: Install dependencies run: pnpm install --frozen-lockfile + - name: Build CLI for localhost integration tests + run: pnpm run build + - name: Run tests run: pnpm run test diff --git a/README.md b/README.md index 195dfd7..c0a3cc7 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,7 @@ [![License](https://img.shields.io/npm/l/@hackmd/hackmd-cli.svg)](https://github.com/hackmdio/hackmd-cli/blob/master/package.json) * [Usage](#usage) +* [Full API access](#full-api-access) * [Commands](#commands) * [Configuration](#configuration) * [License](#license) @@ -31,7 +32,7 @@ $ npm install -g @hackmd/hackmd-cli $ hackmd-cli COMMAND running command... $ hackmd-cli (--version|-v) -@hackmd/hackmd-cli/2.5.1 darwin-arm64 node-v24.22.0 +@hackmd/hackmd-cli/2.5.1 darwin-arm64 node-v24.22.1 $ hackmd-cli --help [COMMAND] USAGE $ hackmd-cli COMMAND @@ -45,6 +46,23 @@ Run `hackmd-cli autocomplete bash`, `hackmd-cli autocomplete zsh`, or `hackmd-cl Fish completion is generated in the CLI cache. Its setup instructions copy the generated file into your user completion directory; no system directory or `pkg-config` is required. Run the setup again after upgrading the CLI. +## Full API access + +Use the focused `notes`, `folders`, and other commands for common workflows. For other API operations, use `api`: + +```bash +hackmd-cli api operations +hackmd-cli api describe GetTeamNote +hackmd-cli api call GetTeamNote --path teampath=docs --path noteId=abc +hackmd-cli api call ListVersions --path noteId=abc --query limit=10 +hackmd-cli api call CreateNote --body @note.json +hackmd-cli api call UploadNoteImage --path noteId=abc --file image=@photo.png +``` + +Use repeated `--path key=value`, `--query key=value`, and `--header 'Name: value'` flags. `--body` accepts JSON text, `@file`, or `-` for stdin. For multipart image uploads, use `--file image=@path`; the file extension sets its MIME type, or use `--mime` to override it. `--include` prints HTTP status and headers before the response body. Empty 204/304 responses print no body; NDJSON is printed unchanged. Errors exit nonzero. + +`api operations` and `api describe` need no connection or token. They use the API client bundled with this CLI, so older HackMD EE servers may not support every operation. `api call` uses the same access token and endpoint configuration as other commands. Writes are not retried automatically. + ## Configuration ### Set access token @@ -106,6 +124,9 @@ All available configurations are listed in the table below. ## Commands +* [`hackmd-cli api call OPERATIONID`](#hackmd-cli-api-call-operationid) +* [`hackmd-cli api describe OPERATIONID`](#hackmd-cli-api-describe-operationid) +* [`hackmd-cli api operations`](#hackmd-cli-api-operations) * [`hackmd-cli autocomplete [SHELL]`](#hackmd-cli-autocomplete-shell) * [`hackmd-cli export`](#hackmd-cli-export) * [`hackmd-cli folders`](#hackmd-cli-folders) @@ -134,6 +155,72 @@ All available configurations are listed in the table below. * [`hackmd-cli version`](#hackmd-cli-version) * [`hackmd-cli whoami`](#hackmd-cli-whoami) +## `hackmd-cli api call OPERATIONID` + +Call a HackMD API operation + +``` +USAGE + $ hackmd-cli api call OPERATIONID [--body ] [--file ...] [--header ...] [-h] + [--include] [--mime ] [--path ...] [--query ...] + +FLAGS + -h, --help Show CLI help. + --body= JSON value, @file, or - for stdin + --file=... Multipart binary field, e.g. image=@photo.png + --header=... Request header Name: value + --include Include HTTP status and response headers + --mime= MIME type override for --file + --path=... Path parameter key=value + --query=... Query parameter key=value + +DESCRIPTION + Call a HackMD API operation + +EXAMPLES + $ hackmd-cli api call GetTeamNote --path teampath=docs --path noteId=abc + + $ hackmd-cli api call CreateNote --body @note.json + + $ hackmd-cli api call UploadNoteImage --path noteId=abc --file image=@photo.png +``` + +_See code: [src/commands/api/call.ts](https://github.com/hackmdio/hackmd-cli/blob/v2.5.1/src/commands/api/call.ts)_ + +## `hackmd-cli api describe OPERATIONID` + +Show details for an API operation + +``` +USAGE + $ hackmd-cli api describe OPERATIONID [-h] + +FLAGS + -h, --help Show CLI help. + +DESCRIPTION + Show details for an API operation +``` + +_See code: [src/commands/api/describe.ts](https://github.com/hackmdio/hackmd-cli/blob/v2.5.1/src/commands/api/describe.ts)_ + +## `hackmd-cli api operations` + +List available API operations + +``` +USAGE + $ hackmd-cli api operations [-h] + +FLAGS + -h, --help Show CLI help. + +DESCRIPTION + List available API operations +``` + +_See code: [src/commands/api/operations.ts](https://github.com/hackmdio/hackmd-cli/blob/v2.5.1/src/commands/api/operations.ts)_ + ## `hackmd-cli autocomplete [SHELL]` Display autocomplete installation instructions @@ -310,23 +397,28 @@ Update folder ``` USAGE - $ hackmd-cli folders update [--color ] [--description ] [--folderId ] [-h] [--icon ] - [--name ] [--parentFolderId ] + $ hackmd-cli folders update [--clear description|icon|color...] [--color ] [--description ] + [--folderId ] [-h] [--icon ] [--name ] [--parentFolderId ] [--root] FLAGS -h, --help Show CLI help. + --clear=