From 29533ad113ebe2bc4d43933cb742fff5aabf17d5 Mon Sep 17 00:00:00 2001 From: Julia <101819212+juliamrch@users.noreply.github.com> Date: Fri, 24 Jul 2026 17:12:31 +0200 Subject: [PATCH 1/3] feat: build the structure for koh docs generation --- .github/workflows/generate-koh-cli-docs.yaml | 98 +++++++++++++++++++ app/_data/products/koh.yml | 7 ++ app/_data/tools/koh-cli.yml | 1 + .../koh/reference/0.3/collection.md | 26 +++++ .../koh/reference/0.3/collection_create.md | 24 +++++ .../koh/reference/0.3/collection_list.md | 22 +++++ .../koh/reference/0.3/collection_remove.md | 18 ++++ .../koh/reference/0.3/collection_show.md | 18 ++++ .../koh/reference/0.3/collection_update.md | 23 +++++ app/_references/koh/reference/0.3/document.md | 25 +++++ .../koh/reference/0.3/document_list.md | 18 ++++ .../koh/reference/0.3/document_remove.md | 18 ++++ .../koh/reference/0.3/document_show.md | 18 ++++ .../koh/reference/0.3/document_spec.md | 23 +++++ .../reference/0.3/document_spec_operation.md | 24 +++++ .../0.3/document_spec_operation_list.md | 22 +++++ .../0.3/document_spec_operation_search.md | 24 +++++ .../0.3/document_spec_operation_show.md | 23 +++++ .../koh/reference/0.3/document_spec_show.md | 22 +++++ .../koh/reference/0.3/environment.md | 26 +++++ .../koh/reference/0.3/environment_create.md | 27 +++++ .../koh/reference/0.3/environment_list.md | 24 +++++ .../koh/reference/0.3/environment_remove.md | 23 +++++ .../koh/reference/0.3/environment_show.md | 23 +++++ .../koh/reference/0.3/environment_update.md | 26 +++++ app/_references/koh/reference/0.3/import.md | 23 +++++ .../koh/reference/0.3/import_curl.md | 25 +++++ .../koh/reference/0.3/import_oas.md | 23 +++++ .../reference/0.3/import_oas_collection.md | 22 +++++ .../koh/reference/0.3/import_oas_document.md | 22 +++++ app/_references/koh/reference/0.3/index.md | 67 +++++++++++++ app/_references/koh/reference/0.3/request.md | 27 +++++ .../koh/reference/0.3/request_create.md | 32 ++++++ .../koh/reference/0.3/request_list.md | 23 +++++ .../koh/reference/0.3/request_remove.md | 22 +++++ .../koh/reference/0.3/request_run.md | 31 ++++++ .../koh/reference/0.3/request_show.md | 22 +++++ .../koh/reference/0.3/request_update.md | 31 ++++++ app/_references/koh/reference/0.3/skills.md | 22 +++++ .../koh/reference/0.3/skills_install.md | 22 +++++ 40 files changed, 1017 insertions(+) create mode 100644 .github/workflows/generate-koh-cli-docs.yaml create mode 100644 app/_data/products/koh.yml create mode 100644 app/_data/tools/koh-cli.yml create mode 100644 app/_references/koh/reference/0.3/collection.md create mode 100644 app/_references/koh/reference/0.3/collection_create.md create mode 100644 app/_references/koh/reference/0.3/collection_list.md create mode 100644 app/_references/koh/reference/0.3/collection_remove.md create mode 100644 app/_references/koh/reference/0.3/collection_show.md create mode 100644 app/_references/koh/reference/0.3/collection_update.md create mode 100644 app/_references/koh/reference/0.3/document.md create mode 100644 app/_references/koh/reference/0.3/document_list.md create mode 100644 app/_references/koh/reference/0.3/document_remove.md create mode 100644 app/_references/koh/reference/0.3/document_show.md create mode 100644 app/_references/koh/reference/0.3/document_spec.md create mode 100644 app/_references/koh/reference/0.3/document_spec_operation.md create mode 100644 app/_references/koh/reference/0.3/document_spec_operation_list.md create mode 100644 app/_references/koh/reference/0.3/document_spec_operation_search.md create mode 100644 app/_references/koh/reference/0.3/document_spec_operation_show.md create mode 100644 app/_references/koh/reference/0.3/document_spec_show.md create mode 100644 app/_references/koh/reference/0.3/environment.md create mode 100644 app/_references/koh/reference/0.3/environment_create.md create mode 100644 app/_references/koh/reference/0.3/environment_list.md create mode 100644 app/_references/koh/reference/0.3/environment_remove.md create mode 100644 app/_references/koh/reference/0.3/environment_show.md create mode 100644 app/_references/koh/reference/0.3/environment_update.md create mode 100644 app/_references/koh/reference/0.3/import.md create mode 100644 app/_references/koh/reference/0.3/import_curl.md create mode 100644 app/_references/koh/reference/0.3/import_oas.md create mode 100644 app/_references/koh/reference/0.3/import_oas_collection.md create mode 100644 app/_references/koh/reference/0.3/import_oas_document.md create mode 100644 app/_references/koh/reference/0.3/index.md create mode 100644 app/_references/koh/reference/0.3/request.md create mode 100644 app/_references/koh/reference/0.3/request_create.md create mode 100644 app/_references/koh/reference/0.3/request_list.md create mode 100644 app/_references/koh/reference/0.3/request_remove.md create mode 100644 app/_references/koh/reference/0.3/request_run.md create mode 100644 app/_references/koh/reference/0.3/request_show.md create mode 100644 app/_references/koh/reference/0.3/request_update.md create mode 100644 app/_references/koh/reference/0.3/skills.md create mode 100644 app/_references/koh/reference/0.3/skills_install.md diff --git a/.github/workflows/generate-koh-cli-docs.yaml b/.github/workflows/generate-koh-cli-docs.yaml new file mode 100644 index 00000000000..19ba6614c36 --- /dev/null +++ b/.github/workflows/generate-koh-cli-docs.yaml @@ -0,0 +1,98 @@ +name: Generate Koh CLI Reference Docs + +on: + workflow_dispatch: + inputs: + koh_branch: + description: 'Branch to use from koh repository' + required: true + default: 'main' + type: string + dev_site_base_branch: + description: 'Dev site base branch, e.g. main' + required: true + type: string + +permissions: + contents: write + pull-requests: write + +jobs: + generate-koh-cli-docs: + name: Generate Koh CLI Reference Docs + runs-on: ubuntu-latest + timeout-minutes: 30 + steps: + - name: Harden Runner + uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4 + with: + egress-policy: audit + + - name: Create GitHub App Token + uses: actions/create-github-app-token@f8d387b68d61c58ab83c6c016672934102569859 + id: app-token + with: + app-id: ${{ vars.GH_APP_KONG_DOCS_ID }} + private-key: ${{ secrets.GH_APP_KONG_DOCS_SECRET }} + owner: Kong + + - name: Checkout developer.konghq.com + uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7 + with: + token: ${{ steps.app-token.outputs.token }} + ref: ${{ inputs.dev_site_base_branch }} + + - name: Checkout koh repository + uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7 + with: + repository: 'kong-insomnia/koh' + token: ${{ steps.app-token.outputs.token }} + path: 'insomnia' + ref: ${{ inputs.koh_branch }} + + - name: Setup Node.js + uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6 + with: + node-version: 22 + cache: npm + cache-dependency-path: insomnia/package-lock.json + + - name: install dependencies + working-directory: insomnia + run: npm ci --ignore-scripts + + - name: Generate Koh CLI reference docs + working-directory: insomnia + run: npm run build + + - name: Copy generated docs to developer.konghq.com + run: | + mkdir -p app/_references/koh/reference/ + cp -R ./insomnia/reference/koh/* app/_references/koh/reference/ + + - name: Check for changes + id: changes + run: | + if [ -n "$(git status --porcelain app/_references/koh/reference/)" ]; then + echo "changed=true" >> $GITHUB_OUTPUT + else + echo "changed=false" >> $GITHUB_OUTPUT + fi + + - name: Create pull request + if: steps.changes.outputs.changed == 'true' + uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8 + with: + title: Generate Koh CLI reference docs + commit-message: Generate Koh CLI reference docs + labels: skip-changelog,review:general + token: ${{ steps.app-token.outputs.token }} + branch: auto/generate-koh-cli-docs-${{ github.run_number }} + base: ${{ inputs.dev_site_base_branch }} + add-paths: | + app/_references/koh/reference/** + + - name: No changes detected + if: steps.changes.outputs.changed == 'false' + run: | + echo "No changes detected in the Koh CLI reference. No pull request will be created." diff --git a/app/_data/products/koh.yml b/app/_data/products/koh.yml new file mode 100644 index 00000000000..a8130c8ff4d --- /dev/null +++ b/app/_data/products/koh.yml @@ -0,0 +1,7 @@ +name: Koh CLI +icon: /_assets/icons/products/insomnia.svg + +releases: + - release: "0.3" + version: "0.3.5" + latest: true diff --git a/app/_data/tools/koh-cli.yml b/app/_data/tools/koh-cli.yml new file mode 100644 index 00000000000..f5bd0f1dd8c --- /dev/null +++ b/app/_data/tools/koh-cli.yml @@ -0,0 +1 @@ +name: Koh CLI \ No newline at end of file diff --git a/app/_references/koh/reference/0.3/collection.md b/app/_references/koh/reference/0.3/collection.md new file mode 100644 index 00000000000..f1305005fc6 --- /dev/null +++ b/app/_references/koh/reference/0.3/collection.md @@ -0,0 +1,26 @@ +--- +title: collection +--- + +## Command Description + +Manage collections + +## Syntax + +`collection [options] [command]` + +## Global Flags + +- `--project `: Path to the Git Project directory (defaults to current directory) +- `--agent`: Output structured JSON for agent/LLM consumption +- `--verbose`: Show detailed logs + +## Subcommands + +- [`collection list`](/koh/reference/collection_list/{{page.release}}/): List all collections in the project +- [`collection show`](/koh/reference/collection_show/{{page.release}}/): Show collection details +- [`collection create`](/koh/reference/collection_create/{{page.release}}/): Create a new empty collection +- [`collection update`](/koh/reference/collection_update/{{page.release}}/): Update a collection +- [`collection remove`](/koh/reference/collection_remove/{{page.release}}/): Remove a collection + diff --git a/app/_references/koh/reference/0.3/collection_create.md b/app/_references/koh/reference/0.3/collection_create.md new file mode 100644 index 00000000000..7139e06896a --- /dev/null +++ b/app/_references/koh/reference/0.3/collection_create.md @@ -0,0 +1,24 @@ +--- +title: collection create +--- + +## Command Description + +Create a new empty collection + +## Syntax + +`collection create [options]` + +## Local Flags + +- `--name `: Collection name +- `--description `: Collection description +- `--file-path `: Custom YAML file path (relative to project dir) + +## Global Flags + +- `--project `: Path to the Git Project directory (defaults to current directory) +- `--agent`: Output structured JSON for agent/LLM consumption +- `--verbose`: Show detailed logs + diff --git a/app/_references/koh/reference/0.3/collection_list.md b/app/_references/koh/reference/0.3/collection_list.md new file mode 100644 index 00000000000..b076e00b667 --- /dev/null +++ b/app/_references/koh/reference/0.3/collection_list.md @@ -0,0 +1,22 @@ +--- +title: collection list +--- + +## Command Description + +List all collections in the project + +## Syntax + +`collection list [options]` + +## Local Flags + +- `--query `: Case-insensitive query across collection name and description + +## Global Flags + +- `--project `: Path to the Git Project directory (defaults to current directory) +- `--agent`: Output structured JSON for agent/LLM consumption +- `--verbose`: Show detailed logs + diff --git a/app/_references/koh/reference/0.3/collection_remove.md b/app/_references/koh/reference/0.3/collection_remove.md new file mode 100644 index 00000000000..815c130e723 --- /dev/null +++ b/app/_references/koh/reference/0.3/collection_remove.md @@ -0,0 +1,18 @@ +--- +title: collection remove +--- + +## Command Description + +Remove a collection + +## Syntax + +`collection remove [options] ` + +## Global Flags + +- `--project `: Path to the Git Project directory (defaults to current directory) +- `--agent`: Output structured JSON for agent/LLM consumption +- `--verbose`: Show detailed logs + diff --git a/app/_references/koh/reference/0.3/collection_show.md b/app/_references/koh/reference/0.3/collection_show.md new file mode 100644 index 00000000000..623c05d4fcc --- /dev/null +++ b/app/_references/koh/reference/0.3/collection_show.md @@ -0,0 +1,18 @@ +--- +title: collection show +--- + +## Command Description + +Show collection details + +## Syntax + +`collection show [options] ` + +## Global Flags + +- `--project `: Path to the Git Project directory (defaults to current directory) +- `--agent`: Output structured JSON for agent/LLM consumption +- `--verbose`: Show detailed logs + diff --git a/app/_references/koh/reference/0.3/collection_update.md b/app/_references/koh/reference/0.3/collection_update.md new file mode 100644 index 00000000000..29a6e1d7632 --- /dev/null +++ b/app/_references/koh/reference/0.3/collection_update.md @@ -0,0 +1,23 @@ +--- +title: collection update +--- + +## Command Description + +Update a collection + +## Syntax + +`collection update [options] ` + +## Local Flags + +- `--name `: New collection name +- `--description `: New collection description + +## Global Flags + +- `--project `: Path to the Git Project directory (defaults to current directory) +- `--agent`: Output structured JSON for agent/LLM consumption +- `--verbose`: Show detailed logs + diff --git a/app/_references/koh/reference/0.3/document.md b/app/_references/koh/reference/0.3/document.md new file mode 100644 index 00000000000..ecc9ad49be7 --- /dev/null +++ b/app/_references/koh/reference/0.3/document.md @@ -0,0 +1,25 @@ +--- +title: document +--- + +## Command Description + +Manage API specifications + +## Syntax + +`document [options] [command]` + +## Global Flags + +- `--project `: Path to the Git Project directory (defaults to current directory) +- `--agent`: Output structured JSON for agent/LLM consumption +- `--verbose`: Show detailed logs + +## Subcommands + +- [`document list`](/koh/reference/document_list/{{page.release}}/): List all documents in the project +- [`document show`](/koh/reference/document_show/{{page.release}}/): Show document details +- [`document remove`](/koh/reference/document_remove/{{page.release}}/): Remove a document +- [`document spec`](/koh/reference/document_spec/{{page.release}}/): Inspect specs within documents + diff --git a/app/_references/koh/reference/0.3/document_list.md b/app/_references/koh/reference/0.3/document_list.md new file mode 100644 index 00000000000..b525b45ea97 --- /dev/null +++ b/app/_references/koh/reference/0.3/document_list.md @@ -0,0 +1,18 @@ +--- +title: document list +--- + +## Command Description + +List all documents in the project + +## Syntax + +`document list [options]` + +## Global Flags + +- `--project `: Path to the Git Project directory (defaults to current directory) +- `--agent`: Output structured JSON for agent/LLM consumption +- `--verbose`: Show detailed logs + diff --git a/app/_references/koh/reference/0.3/document_remove.md b/app/_references/koh/reference/0.3/document_remove.md new file mode 100644 index 00000000000..e4168086a84 --- /dev/null +++ b/app/_references/koh/reference/0.3/document_remove.md @@ -0,0 +1,18 @@ +--- +title: document remove +--- + +## Command Description + +Remove a document + +## Syntax + +`document remove [options] ` + +## Global Flags + +- `--project `: Path to the Git Project directory (defaults to current directory) +- `--agent`: Output structured JSON for agent/LLM consumption +- `--verbose`: Show detailed logs + diff --git a/app/_references/koh/reference/0.3/document_show.md b/app/_references/koh/reference/0.3/document_show.md new file mode 100644 index 00000000000..602cbf46335 --- /dev/null +++ b/app/_references/koh/reference/0.3/document_show.md @@ -0,0 +1,18 @@ +--- +title: document show +--- + +## Command Description + +Show document details + +## Syntax + +`document show [options] ` + +## Global Flags + +- `--project `: Path to the Git Project directory (defaults to current directory) +- `--agent`: Output structured JSON for agent/LLM consumption +- `--verbose`: Show detailed logs + diff --git a/app/_references/koh/reference/0.3/document_spec.md b/app/_references/koh/reference/0.3/document_spec.md new file mode 100644 index 00000000000..28cdf17730b --- /dev/null +++ b/app/_references/koh/reference/0.3/document_spec.md @@ -0,0 +1,23 @@ +--- +title: document spec +--- + +## Command Description + +Inspect specs within documents + +## Syntax + +`document spec [options] [command]` + +## Global Flags + +- `--project `: Path to the Git Project directory (defaults to current directory) +- `--agent`: Output structured JSON for agent/LLM consumption +- `--verbose`: Show detailed logs + +## Subcommands + +- [`document spec show`](/koh/reference/document_spec_show/{{page.release}}/): Show the document spec +- [`document spec operation`](/koh/reference/document_spec_operation/{{page.release}}/): Inspect operations in a document spec + diff --git a/app/_references/koh/reference/0.3/document_spec_operation.md b/app/_references/koh/reference/0.3/document_spec_operation.md new file mode 100644 index 00000000000..759aede98eb --- /dev/null +++ b/app/_references/koh/reference/0.3/document_spec_operation.md @@ -0,0 +1,24 @@ +--- +title: document spec operation +--- + +## Command Description + +Inspect operations in a document spec + +## Syntax + +`document spec operation [options] [command]` + +## Global Flags + +- `--project `: Path to the Git Project directory (defaults to current directory) +- `--agent`: Output structured JSON for agent/LLM consumption +- `--verbose`: Show detailed logs + +## Subcommands + +- [`document spec operation search`](/koh/reference/document_spec_operation_search/{{page.release}}/): Search operations in a document spec +- [`document spec operation list`](/koh/reference/document_spec_operation_list/{{page.release}}/): List operations in a document spec +- [`document spec operation show`](/koh/reference/document_spec_operation_show/{{page.release}}/): Show a single operation in a document spec + diff --git a/app/_references/koh/reference/0.3/document_spec_operation_list.md b/app/_references/koh/reference/0.3/document_spec_operation_list.md new file mode 100644 index 00000000000..b09cf5b4560 --- /dev/null +++ b/app/_references/koh/reference/0.3/document_spec_operation_list.md @@ -0,0 +1,22 @@ +--- +title: document spec operation list +--- + +## Command Description + +List operations in a document spec + +## Syntax + +`document spec operation list [options]` + +## Local Flags + +- `--document `: Document name or ID + +## Global Flags + +- `--project `: Path to the Git Project directory (defaults to current directory) +- `--agent`: Output structured JSON for agent/LLM consumption +- `--verbose`: Show detailed logs + diff --git a/app/_references/koh/reference/0.3/document_spec_operation_search.md b/app/_references/koh/reference/0.3/document_spec_operation_search.md new file mode 100644 index 00000000000..97741a1604d --- /dev/null +++ b/app/_references/koh/reference/0.3/document_spec_operation_search.md @@ -0,0 +1,24 @@ +--- +title: document spec operation search +--- + +## Command Description + +Search operations in a document spec + +## Syntax + +`document spec operation search [options]` + +## Local Flags + +- `--document `: Document name or ID +- `--query `: Case-insensitive query across operation fields +- `--filter-json `: Structured JSON filter + +## Global Flags + +- `--project `: Path to the Git Project directory (defaults to current directory) +- `--agent`: Output structured JSON for agent/LLM consumption +- `--verbose`: Show detailed logs + diff --git a/app/_references/koh/reference/0.3/document_spec_operation_show.md b/app/_references/koh/reference/0.3/document_spec_operation_show.md new file mode 100644 index 00000000000..cc4d2ee84f2 --- /dev/null +++ b/app/_references/koh/reference/0.3/document_spec_operation_show.md @@ -0,0 +1,23 @@ +--- +title: document spec operation show +--- + +## Command Description + +Show a single operation in a document spec + +## Syntax + +`document spec operation show [options]` + +## Local Flags + +- `--document `: Document name or ID +- `--operation-id `: Operation ID + +## Global Flags + +- `--project `: Path to the Git Project directory (defaults to current directory) +- `--agent`: Output structured JSON for agent/LLM consumption +- `--verbose`: Show detailed logs + diff --git a/app/_references/koh/reference/0.3/document_spec_show.md b/app/_references/koh/reference/0.3/document_spec_show.md new file mode 100644 index 00000000000..e023d32dbb5 --- /dev/null +++ b/app/_references/koh/reference/0.3/document_spec_show.md @@ -0,0 +1,22 @@ +--- +title: document spec show +--- + +## Command Description + +Show the document spec + +## Syntax + +`document spec show [options]` + +## Local Flags + +- `--document `: Document name or ID + +## Global Flags + +- `--project `: Path to the Git Project directory (defaults to current directory) +- `--agent`: Output structured JSON for agent/LLM consumption +- `--verbose`: Show detailed logs + diff --git a/app/_references/koh/reference/0.3/environment.md b/app/_references/koh/reference/0.3/environment.md new file mode 100644 index 00000000000..7c223e6b3b0 --- /dev/null +++ b/app/_references/koh/reference/0.3/environment.md @@ -0,0 +1,26 @@ +--- +title: environment +--- + +## Command Description + +Manage environments + +## Syntax + +`environment [options] [command]` + +## Global Flags + +- `--project `: Path to the Git Project directory (defaults to current directory) +- `--agent`: Output structured JSON for agent/LLM consumption +- `--verbose`: Show detailed logs + +## Subcommands + +- [`environment list`](/koh/reference/environment_list/{{page.release}}/): List all environments, or sub-environments when --environment is given +- [`environment show`](/koh/reference/environment_show/{{page.release}}/): Show environment details, or a sub-environment when --environment is given +- [`environment create`](/koh/reference/environment_create/{{page.release}}/): Create a new environment, or a sub-environment when --environment is given +- [`environment update`](/koh/reference/environment_update/{{page.release}}/): Update environment metadata, or a sub-environment when --environment is given +- [`environment remove`](/koh/reference/environment_remove/{{page.release}}/): Remove an environment, or a sub-environment when --environment is given + diff --git a/app/_references/koh/reference/0.3/environment_create.md b/app/_references/koh/reference/0.3/environment_create.md new file mode 100644 index 00000000000..47839b56e74 --- /dev/null +++ b/app/_references/koh/reference/0.3/environment_create.md @@ -0,0 +1,27 @@ +--- +title: environment create +--- + +## Command Description + +Create a new environment, or a sub-environment when --environment is given + +## Syntax + +`environment create [options]` + +## Local Flags + +- `--name `: Environment name +- `--description `: Environment description +- `--color `: Sub-environment color (only used with --environment) +- `--is-private `: Whether the sub-environment is private (true/false; only used with --environment) +- `--environment `: Parent environment to create a sub-environment within +- `--global`: Create within/as a global environment + +## Global Flags + +- `--project `: Path to the Git Project directory (defaults to current directory) +- `--agent`: Output structured JSON for agent/LLM consumption +- `--verbose`: Show detailed logs + diff --git a/app/_references/koh/reference/0.3/environment_list.md b/app/_references/koh/reference/0.3/environment_list.md new file mode 100644 index 00000000000..0fa710373df --- /dev/null +++ b/app/_references/koh/reference/0.3/environment_list.md @@ -0,0 +1,24 @@ +--- +title: environment list +--- + +## Command Description + +List all environments, or sub-environments when --environment is given + +## Syntax + +`environment list [options]` + +## Local Flags + +- `--query `: Case-insensitive query across environment name and description +- `--environment `: Parent environment to list sub-environments of +- `--global`: List global environments + +## Global Flags + +- `--project `: Path to the Git Project directory (defaults to current directory) +- `--agent`: Output structured JSON for agent/LLM consumption +- `--verbose`: Show detailed logs + diff --git a/app/_references/koh/reference/0.3/environment_remove.md b/app/_references/koh/reference/0.3/environment_remove.md new file mode 100644 index 00000000000..61f154fa990 --- /dev/null +++ b/app/_references/koh/reference/0.3/environment_remove.md @@ -0,0 +1,23 @@ +--- +title: environment remove +--- + +## Command Description + +Remove an environment, or a sub-environment when --environment is given + +## Syntax + +`environment remove [options] ` + +## Local Flags + +- `--environment `: Parent environment containing the sub-environment to remove +- `--global`: Remove a global environment + +## Global Flags + +- `--project `: Path to the Git Project directory (defaults to current directory) +- `--agent`: Output structured JSON for agent/LLM consumption +- `--verbose`: Show detailed logs + diff --git a/app/_references/koh/reference/0.3/environment_show.md b/app/_references/koh/reference/0.3/environment_show.md new file mode 100644 index 00000000000..da98278f916 --- /dev/null +++ b/app/_references/koh/reference/0.3/environment_show.md @@ -0,0 +1,23 @@ +--- +title: environment show +--- + +## Command Description + +Show environment details, or a sub-environment when --environment is given + +## Syntax + +`environment show [options] ` + +## Local Flags + +- `--environment `: Parent environment containing the sub-environment to show +- `--global`: Show a global environment + +## Global Flags + +- `--project `: Path to the Git Project directory (defaults to current directory) +- `--agent`: Output structured JSON for agent/LLM consumption +- `--verbose`: Show detailed logs + diff --git a/app/_references/koh/reference/0.3/environment_update.md b/app/_references/koh/reference/0.3/environment_update.md new file mode 100644 index 00000000000..42d4f81bb67 --- /dev/null +++ b/app/_references/koh/reference/0.3/environment_update.md @@ -0,0 +1,26 @@ +--- +title: environment update +--- + +## Command Description + +Update environment metadata, or a sub-environment when --environment is given + +## Syntax + +`environment update [options] ` + +## Local Flags + +- `--name `: New name +- `--description `: New description +- `--color `: New color +- `--environment `: Parent environment containing the sub-environment to update +- `--global`: Update within/as a global environment + +## Global Flags + +- `--project `: Path to the Git Project directory (defaults to current directory) +- `--agent`: Output structured JSON for agent/LLM consumption +- `--verbose`: Show detailed logs + diff --git a/app/_references/koh/reference/0.3/import.md b/app/_references/koh/reference/0.3/import.md new file mode 100644 index 00000000000..47ee5af07f1 --- /dev/null +++ b/app/_references/koh/reference/0.3/import.md @@ -0,0 +1,23 @@ +--- +title: import +--- + +## Command Description + +Import resources into a project + +## Syntax + +`import [options] [command]` + +## Global Flags + +- `--project `: Path to the Git Project directory (defaults to current directory) +- `--agent`: Output structured JSON for agent/LLM consumption +- `--verbose`: Show detailed logs + +## Subcommands + +- [`import oas`](/koh/reference/import_oas/{{page.release}}/): Import an OpenAPI 3.x or Swagger 2.0 Specification (YAML or JSON) +- [`import curl`](/koh/reference/import_curl/{{page.release}}/): Import a cURL command as a request + diff --git a/app/_references/koh/reference/0.3/import_curl.md b/app/_references/koh/reference/0.3/import_curl.md new file mode 100644 index 00000000000..e18b301279a --- /dev/null +++ b/app/_references/koh/reference/0.3/import_curl.md @@ -0,0 +1,25 @@ +--- +title: import curl +--- + +## Command Description + +Import a cURL command as a request + +## Syntax + +`import curl [options] [curl]` + +## Local Flags + +- `--from-file `: Read the cURL command from a file (avoids shell escaping) +- `--collection `: Collection to create the request in +- `--parent `: Parent ID (collection or folder); overrides --collection +- `--name `: Request name (defaults to "METHOD ") + +## Global Flags + +- `--project `: Path to the Git Project directory (defaults to current directory) +- `--agent`: Output structured JSON for agent/LLM consumption +- `--verbose`: Show detailed logs + diff --git a/app/_references/koh/reference/0.3/import_oas.md b/app/_references/koh/reference/0.3/import_oas.md new file mode 100644 index 00000000000..aed051fcf6f --- /dev/null +++ b/app/_references/koh/reference/0.3/import_oas.md @@ -0,0 +1,23 @@ +--- +title: import oas +--- + +## Command Description + +Import an OpenAPI 3.x or Swagger 2.0 Specification (YAML or JSON) + +## Syntax + +`import oas [options] [command]` + +## Global Flags + +- `--project `: Path to the Git Project directory (defaults to current directory) +- `--agent`: Output structured JSON for agent/LLM consumption +- `--verbose`: Show detailed logs + +## Subcommands + +- [`import oas collection`](/koh/reference/import_oas_collection/{{page.release}}/): Import an OpenAPI 3.x or Swagger 2.0 Specification as a collection +- [`import oas document`](/koh/reference/import_oas_document/{{page.release}}/): Import an OpenAPI 3.x or Swagger 2.0 Specification as an Insomnia spec document + diff --git a/app/_references/koh/reference/0.3/import_oas_collection.md b/app/_references/koh/reference/0.3/import_oas_collection.md new file mode 100644 index 00000000000..eb1add9f349 --- /dev/null +++ b/app/_references/koh/reference/0.3/import_oas_collection.md @@ -0,0 +1,22 @@ +--- +title: import oas collection +--- + +## Command Description + +Import an OpenAPI 3.x or Swagger 2.0 Specification as a collection + +## Syntax + +`import oas collection [options] ` + +## Local Flags + +- `--target `: Merge into an existing collection or create a collection with this name + +## Global Flags + +- `--project `: Path to the Git Project directory (defaults to current directory) +- `--agent`: Output structured JSON for agent/LLM consumption +- `--verbose`: Show detailed logs + diff --git a/app/_references/koh/reference/0.3/import_oas_document.md b/app/_references/koh/reference/0.3/import_oas_document.md new file mode 100644 index 00000000000..cfef5939fa9 --- /dev/null +++ b/app/_references/koh/reference/0.3/import_oas_document.md @@ -0,0 +1,22 @@ +--- +title: import oas document +--- + +## Command Description + +Import an OpenAPI 3.x or Swagger 2.0 Specification as an Insomnia spec document + +## Syntax + +`import oas document [options] ` + +## Local Flags + +- `--target `: Replace an existing document or create a document with this name + +## Global Flags + +- `--project `: Path to the Git Project directory (defaults to current directory) +- `--agent`: Output structured JSON for agent/LLM consumption +- `--verbose`: Show detailed logs + diff --git a/app/_references/koh/reference/0.3/index.md b/app/_references/koh/reference/0.3/index.md new file mode 100644 index 00000000000..7e8885b199e --- /dev/null +++ b/app/_references/koh/reference/0.3/index.md @@ -0,0 +1,67 @@ +--- +title: CLI Documentation +--- + +## Global Flags + +- `--project `: Path to the Git Project directory (defaults to current directory) +- `--agent`: Output structured JSON for agent/LLM consumption +- `--verbose`: Show detailed logs + +## Commands + +- [`collection`](/koh/reference/collection/{{page.release}}/): Manage collections +- [`document`](/koh/reference/document/{{page.release}}/): Manage API specifications +- [`environment`](/koh/reference/environment/{{page.release}}/): Manage environments +- [`import`](/koh/reference/import/{{page.release}}/): Import resources into a project +- [`request`](/koh/reference/request/{{page.release}}/): Manage requests within collections +- [`skills`](/koh/reference/skills/{{page.release}}/): Manage agent skills + +## Subcommands + +- [`collection list`](/koh/reference/collection_list/{{page.release}}/): List all collections in the project +- [`collection show`](/koh/reference/collection_show/{{page.release}}/): Show collection details +- [`collection create`](/koh/reference/collection_create/{{page.release}}/): Create a new empty collection +- [`collection update`](/koh/reference/collection_update/{{page.release}}/): Update a collection +- [`collection remove`](/koh/reference/collection_remove/{{page.release}}/): Remove a collection + +## Subcommands + +- [`document list`](/koh/reference/document_list/{{page.release}}/): List all documents in the project +- [`document show`](/koh/reference/document_show/{{page.release}}/): Show document details +- [`document remove`](/koh/reference/document_remove/{{page.release}}/): Remove a document +- [`document spec`](/koh/reference/document_spec/{{page.release}}/): Inspect specs within documents +- [`document spec show`](/koh/reference/document_spec_show/{{page.release}}/): Show the document spec +- [`document spec operation`](/koh/reference/document_spec_operation/{{page.release}}/): Inspect operations in a document spec +- [`document spec operation search`](/koh/reference/document_spec_operation_search/{{page.release}}/): Search operations in a document spec +- [`document spec operation list`](/koh/reference/document_spec_operation_list/{{page.release}}/): List operations in a document spec +- [`document spec operation show`](/koh/reference/document_spec_operation_show/{{page.release}}/): Show a single operation in a document spec + +## Subcommands + +- [`environment list`](/koh/reference/environment_list/{{page.release}}/): List all environments, or sub-environments when --environment is given +- [`environment show`](/koh/reference/environment_show/{{page.release}}/): Show environment details, or a sub-environment when --environment is given +- [`environment create`](/koh/reference/environment_create/{{page.release}}/): Create a new environment, or a sub-environment when --environment is given +- [`environment update`](/koh/reference/environment_update/{{page.release}}/): Update environment metadata, or a sub-environment when --environment is given +- [`environment remove`](/koh/reference/environment_remove/{{page.release}}/): Remove an environment, or a sub-environment when --environment is given + +## Subcommands + +- [`import oas`](/koh/reference/import_oas/{{page.release}}/): Import an OpenAPI 3.x or Swagger 2.0 Specification (YAML or JSON) +- [`import oas collection`](/koh/reference/import_oas_collection/{{page.release}}/): Import an OpenAPI 3.x or Swagger 2.0 Specification as a collection +- [`import oas document`](/koh/reference/import_oas_document/{{page.release}}/): Import an OpenAPI 3.x or Swagger 2.0 Specification as an Insomnia spec document +- [`import curl`](/koh/reference/import_curl/{{page.release}}/): Import a cURL command as a request + +## Subcommands + +- [`request list`](/koh/reference/request_list/{{page.release}}/): List requests, optionally scoped to a collection +- [`request show`](/koh/reference/request_show/{{page.release}}/): Show request details +- [`request create`](/koh/reference/request_create/{{page.release}}/): Create a new request +- [`request update`](/koh/reference/request_update/{{page.release}}/): Update a request +- [`request remove`](/koh/reference/request_remove/{{page.release}}/): Remove a request +- [`request run`](/koh/reference/request_run/{{page.release}}/): Run a request + +## Subcommands + +- [`skills install`](/koh/reference/skills_install/{{page.release}}/): Install bundled agent skill files + diff --git a/app/_references/koh/reference/0.3/request.md b/app/_references/koh/reference/0.3/request.md new file mode 100644 index 00000000000..128d8dcdf7e --- /dev/null +++ b/app/_references/koh/reference/0.3/request.md @@ -0,0 +1,27 @@ +--- +title: request +--- + +## Command Description + +Manage requests within collections + +## Syntax + +`request [options] [command]` + +## Global Flags + +- `--project `: Path to the Git Project directory (defaults to current directory) +- `--agent`: Output structured JSON for agent/LLM consumption +- `--verbose`: Show detailed logs + +## Subcommands + +- [`request list`](/koh/reference/request_list/{{page.release}}/): List requests, optionally scoped to a collection +- [`request show`](/koh/reference/request_show/{{page.release}}/): Show request details +- [`request create`](/koh/reference/request_create/{{page.release}}/): Create a new request +- [`request update`](/koh/reference/request_update/{{page.release}}/): Update a request +- [`request remove`](/koh/reference/request_remove/{{page.release}}/): Remove a request +- [`request run`](/koh/reference/request_run/{{page.release}}/): Run a request + diff --git a/app/_references/koh/reference/0.3/request_create.md b/app/_references/koh/reference/0.3/request_create.md new file mode 100644 index 00000000000..da603276f4c --- /dev/null +++ b/app/_references/koh/reference/0.3/request_create.md @@ -0,0 +1,32 @@ +--- +title: request create +--- + +## Command Description + +Create a new request + +## Syntax + +`request create [options]` + +## Local Flags + +- `--collection `: Collection to create the request in +- `--parent `: Parent ID (collection or folder) +- `--name `: Request name +- `--method `: HTTP method (default: GET) +- `--url `: Request URL +- `--description `: Request description +- `-H, --header `: Headers (format: "Name: Value") +- `-p, --param `: Query params (format: "name=value") +- `--body `: Request body +- `--mime `: Body MIME type (default: application/json) +- `--auth `: Auth (none, bearer:token, basic:user:pass, digest:user:pass, apikey:key:value:addTo, oauth2:key=value;...) + +## Global Flags + +- `--project `: Path to the Git Project directory (defaults to current directory) +- `--agent`: Output structured JSON for agent/LLM consumption +- `--verbose`: Show detailed logs + diff --git a/app/_references/koh/reference/0.3/request_list.md b/app/_references/koh/reference/0.3/request_list.md new file mode 100644 index 00000000000..2b5490bd512 --- /dev/null +++ b/app/_references/koh/reference/0.3/request_list.md @@ -0,0 +1,23 @@ +--- +title: request list +--- + +## Command Description + +List requests, optionally scoped to a collection + +## Syntax + +`request list [options]` + +## Local Flags + +- `--collection `: Scope to a specific collection +- `--query `: Case-insensitive query across request fields + +## Global Flags + +- `--project `: Path to the Git Project directory (defaults to current directory) +- `--agent`: Output structured JSON for agent/LLM consumption +- `--verbose`: Show detailed logs + diff --git a/app/_references/koh/reference/0.3/request_remove.md b/app/_references/koh/reference/0.3/request_remove.md new file mode 100644 index 00000000000..56a8c5dd17a --- /dev/null +++ b/app/_references/koh/reference/0.3/request_remove.md @@ -0,0 +1,22 @@ +--- +title: request remove +--- + +## Command Description + +Remove a request + +## Syntax + +`request remove [options] ` + +## Local Flags + +- `--collection `: Scope search to a specific collection + +## Global Flags + +- `--project `: Path to the Git Project directory (defaults to current directory) +- `--agent`: Output structured JSON for agent/LLM consumption +- `--verbose`: Show detailed logs + diff --git a/app/_references/koh/reference/0.3/request_run.md b/app/_references/koh/reference/0.3/request_run.md new file mode 100644 index 00000000000..6a4e6b1c70a --- /dev/null +++ b/app/_references/koh/reference/0.3/request_run.md @@ -0,0 +1,31 @@ +--- +title: request run +--- + +## Command Description + +Run a request + +## Syntax + +`request run [options] ` + +## Local Flags + +- `--collection `: Scope search to a specific collection +- `--url `: Override request URL +- `--method `: Override HTTP method +- `-H, --header `: Override headers (format: "Name: Value"); replaces all stored headers +- `-p, --param `: Override query params (format: "name=value"); replaces all stored params +- `--body `: Override request body +- `--mime `: Override body MIME type (used with --body) +- `--auth `: Override auth (none, bearer:token, basic:user:pass, digest:user:pass, apikey:key:value[:addTo] ,oauth2:key=value;...) +- `--body-output `: Body output mode: auto (default), or file +- `--max-body-bytes `: Maximum inline body size for auto mode + +## Global Flags + +- `--project `: Path to the Git Project directory (defaults to current directory) +- `--agent`: Output structured JSON for agent/LLM consumption +- `--verbose`: Show detailed logs + diff --git a/app/_references/koh/reference/0.3/request_show.md b/app/_references/koh/reference/0.3/request_show.md new file mode 100644 index 00000000000..8f11e89b130 --- /dev/null +++ b/app/_references/koh/reference/0.3/request_show.md @@ -0,0 +1,22 @@ +--- +title: request show +--- + +## Command Description + +Show request details + +## Syntax + +`request show [options] ` + +## Local Flags + +- `--collection `: Scope search to a specific collection + +## Global Flags + +- `--project `: Path to the Git Project directory (defaults to current directory) +- `--agent`: Output structured JSON for agent/LLM consumption +- `--verbose`: Show detailed logs + diff --git a/app/_references/koh/reference/0.3/request_update.md b/app/_references/koh/reference/0.3/request_update.md new file mode 100644 index 00000000000..86add123c35 --- /dev/null +++ b/app/_references/koh/reference/0.3/request_update.md @@ -0,0 +1,31 @@ +--- +title: request update +--- + +## Command Description + +Update a request + +## Syntax + +`request update [options] ` + +## Local Flags + +- `--collection `: Scope search to a specific collection +- `--name `: New request name +- `--method `: HTTP method +- `--url `: Request URL +- `--description `: Request description +- `-H, --header `: Headers (format: "Name: Value") +- `-p, --param `: Query params (format: "name=value") +- `--body `: Request body +- `--mime `: Body MIME type +- `--auth `: Auth (none, bearer:token, basic:user:pass, digest:user:pass, apikey:key:value:addTo, oauth2:key=value;...) + +## Global Flags + +- `--project `: Path to the Git Project directory (defaults to current directory) +- `--agent`: Output structured JSON for agent/LLM consumption +- `--verbose`: Show detailed logs + diff --git a/app/_references/koh/reference/0.3/skills.md b/app/_references/koh/reference/0.3/skills.md new file mode 100644 index 00000000000..5571b61e19d --- /dev/null +++ b/app/_references/koh/reference/0.3/skills.md @@ -0,0 +1,22 @@ +--- +title: skills +--- + +## Command Description + +Manage agent skills + +## Syntax + +`skills [options] [command]` + +## Global Flags + +- `--project `: Path to the Git Project directory (defaults to current directory) +- `--agent`: Output structured JSON for agent/LLM consumption +- `--verbose`: Show detailed logs + +## Subcommands + +- [`skills install`](/koh/reference/skills_install/{{page.release}}/): Install bundled agent skill files + diff --git a/app/_references/koh/reference/0.3/skills_install.md b/app/_references/koh/reference/0.3/skills_install.md new file mode 100644 index 00000000000..71a3035bc9d --- /dev/null +++ b/app/_references/koh/reference/0.3/skills_install.md @@ -0,0 +1,22 @@ +--- +title: skills install +--- + +## Command Description + +Install bundled agent skill files + +## Syntax + +`skills install [options] [directory]` + +## Local Flags + +- `--force`: Remove existing bundled skill directories before installing + +## Global Flags + +- `--project `: Path to the Git Project directory (defaults to current directory) +- `--agent`: Output structured JSON for agent/LLM consumption +- `--verbose`: Show detailed logs + From 70326b1ac74992cabd294a97be1176df1a161fc8 Mon Sep 17 00:00:00 2001 From: Julia <101819212+juliamrch@users.noreply.github.com> Date: Mon, 27 Jul 2026 11:40:03 +0200 Subject: [PATCH 2/3] add badges to the reference pages: insomnia and koh koh needs to be referenced as a product, because it's not tied to Insomnia versioning yet, so it needs to contain its own versioning --- app/_data/tools/koh-cli.yml | 1 - jekyll.yml | 5 +++++ 2 files changed, 5 insertions(+), 1 deletion(-) delete mode 100644 app/_data/tools/koh-cli.yml diff --git a/app/_data/tools/koh-cli.yml b/app/_data/tools/koh-cli.yml deleted file mode 100644 index f5bd0f1dd8c..00000000000 --- a/app/_data/tools/koh-cli.yml +++ /dev/null @@ -1 +0,0 @@ -name: Koh CLI \ No newline at end of file diff --git a/jekyll.yml b/jekyll.yml index 42f2216d8a1..cd119ef6e98 100644 --- a/jekyll.yml +++ b/jekyll.yml @@ -104,6 +104,11 @@ reference_metadata: tools: - inso-cli + koh: + products: + - koh + - insomnia + gateway: pdk: products: From 7c5233bd5ed75bbbac06b8b0b6620986ba769288 Mon Sep 17 00:00:00 2001 From: Julia <101819212+juliamrch@users.noreply.github.com> Date: Mon, 27 Jul 2026 11:59:42 +0200 Subject: [PATCH 3/3] add push branch to test workflow --- .github/workflows/generate-koh-cli-docs.yaml | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/.github/workflows/generate-koh-cli-docs.yaml b/.github/workflows/generate-koh-cli-docs.yaml index 19ba6614c36..28a289db6f0 100644 --- a/.github/workflows/generate-koh-cli-docs.yaml +++ b/.github/workflows/generate-koh-cli-docs.yaml @@ -12,6 +12,11 @@ on: description: 'Dev site base branch, e.g. main' required: true type: string + # TEMP (remove before merge): lets reviewers run this end-to-end from the + # feature branch, since workflow_dispatch isn't available off the default branch. + push: + branches: + - koh-cli permissions: contents: write @@ -40,7 +45,7 @@ jobs: uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7 with: token: ${{ steps.app-token.outputs.token }} - ref: ${{ inputs.dev_site_base_branch }} + ref: ${{ inputs.dev_site_base_branch || github.ref_name }} # TEMP fallback: remove `|| github.ref_name` with the push trigger - name: Checkout koh repository uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7 @@ -48,7 +53,7 @@ jobs: repository: 'kong-insomnia/koh' token: ${{ steps.app-token.outputs.token }} path: 'insomnia' - ref: ${{ inputs.koh_branch }} + ref: ${{ inputs.koh_branch || 'main' }} # TEMP fallback: remove `|| 'main'` with the push trigger - name: Setup Node.js uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6 @@ -88,7 +93,7 @@ jobs: labels: skip-changelog,review:general token: ${{ steps.app-token.outputs.token }} branch: auto/generate-koh-cli-docs-${{ github.run_number }} - base: ${{ inputs.dev_site_base_branch }} + base: ${{ inputs.dev_site_base_branch || github.ref_name }} # TEMP fallback: remove `|| github.ref_name` with the push trigger add-paths: | app/_references/koh/reference/**