From c439a3306c5ed9f65a72711580b42691ab77e4ef Mon Sep 17 00:00:00 2001 From: Jacob Sussmilch Date: Tue, 28 Jul 2026 12:53:53 +1000 Subject: [PATCH] fix: KEEP-1051 make docs generation actually run, and regenerate go generate ./docs/ silently did nothing. The //go:generate directive sat in generate.go, which carries //go:build ignore, so the file is excluded from the build and never scanned for directives. The command exited 0 having generated nothing, which made two things vacuous: - the docs-check CI job, which compared an unchanged tree against itself and passed in ~16s regardless of drift - the release sync to keeperhub, which regenerates then copies, so it published whatever stale pages happened to be committed Moving the directive into a compiled file fixes both. Regenerating then updates 55 pages and adds 15 that had never been written at all, including kh workflow resume - the only way to enable a workflow from the CLI, previously absent from the reference entirely. Also corrects two statements the generator would have kept publishing: login claimed it opens a browser, which it never does (it prints a URL and waits), and the device-code expiry error suggested rerunning with --no-browser, a flag the CLI has never had. The sync workflow now fails if a tag's committed docs do not match its own command tree, and if it copies fewer pages than were generated, rather than opening a PR that looks authoritative. --- .github/workflows/sync-cli-docs.yml | 22 +++++++++ cmd/auth/login.go | 2 +- docs/doc.go | 14 ++++++ docs/generate.go | 4 +- docs/kh.md | 8 +-- docs/kh_action.md | 1 + docs/kh_action_get.md | 1 + docs/kh_action_list.md | 1 + docs/kh_auth.md | 1 + docs/kh_auth_login.md | 2 +- docs/kh_auth_logout.md | 1 + docs/kh_auth_status.md | 1 + docs/kh_billing.md | 1 + docs/kh_billing_status.md | 1 + docs/kh_billing_usage.md | 1 + docs/kh_chain.md | 33 +++++++++++++ docs/kh_chain_list.md | 60 +++++++++++++++++++++++ docs/kh_completion.md | 1 + docs/kh_config.md | 1 + docs/kh_config_get.md | 1 + docs/kh_config_list.md | 1 + docs/kh_config_set.md | 1 + docs/kh_doctor.md | 1 + docs/kh_execute.md | 1 + docs/kh_execute_contract-call.md | 1 + docs/kh_execute_status.md | 1 + docs/kh_execute_transfer.md | 1 + docs/kh_org.md | 1 + docs/kh_org_list.md | 11 +++++ docs/kh_org_members.md | 11 +++++ docs/kh_org_switch.md | 1 + docs/kh_plugin.md | 37 ++++++++++++++ docs/kh_plugin_get.md | 40 +++++++++++++++ docs/kh_plugin_list.md | 40 +++++++++++++++ docs/kh_project.md | 1 + docs/kh_project_create.md | 1 + docs/kh_project_delete.md | 1 + docs/kh_project_get.md | 1 + docs/kh_project_list.md | 1 + docs/kh_read.md | 59 +++++++++++++++++++++++ docs/kh_run.md | 1 + docs/kh_run_cancel.md | 1 + docs/kh_run_logs.md | 1 + docs/kh_run_status.md | 1 + docs/kh_tag.md | 1 + docs/kh_tag_create.md | 1 + docs/kh_tag_delete.md | 1 + docs/kh_tag_get.md | 1 + docs/kh_tag_list.md | 1 + docs/kh_template.md | 1 + docs/kh_template_deploy.md | 1 + docs/kh_template_list.md | 10 +++- docs/kh_update.md | 1 + docs/kh_version.md | 1 + docs/kh_wallet.md | 32 ++++++++++-- docs/kh_wallet_add.md | 37 ++++++++++++++ docs/kh_wallet_balance.md | 3 +- docs/kh_wallet_feedback.md | 56 +++++++++++++++++++++ docs/kh_wallet_fund.md | 36 ++++++++++++++ docs/kh_wallet_info.md | 35 ++++++++++++++ docs/kh_wallet_link.md | 38 +++++++++++++++ docs/kh_wallet_tokens.md | 3 +- docs/kh_workflow.md | 4 ++ docs/kh_workflow_create.md | 75 +++++++++++++++++++++++++++++ docs/kh_workflow_delete.md | 2 + docs/kh_workflow_get.md | 2 + docs/kh_workflow_go-live.md | 1 + docs/kh_workflow_list.md | 11 ++++- docs/kh_workflow_pause.md | 1 + docs/kh_workflow_resume.md | 39 +++++++++++++++ docs/kh_workflow_run.md | 1 + docs/kh_workflow_update.md | 73 ++++++++++++++++++++++++++++ internal/auth/device.go | 4 +- 73 files changed, 828 insertions(+), 17 deletions(-) create mode 100644 docs/doc.go create mode 100644 docs/kh_chain.md create mode 100644 docs/kh_chain_list.md create mode 100644 docs/kh_plugin.md create mode 100644 docs/kh_plugin_get.md create mode 100644 docs/kh_plugin_list.md create mode 100644 docs/kh_read.md create mode 100644 docs/kh_wallet_add.md create mode 100644 docs/kh_wallet_feedback.md create mode 100644 docs/kh_wallet_fund.md create mode 100644 docs/kh_wallet_info.md create mode 100644 docs/kh_wallet_link.md create mode 100644 docs/kh_workflow_create.md create mode 100644 docs/kh_workflow_resume.md create mode 100644 docs/kh_workflow_update.md diff --git a/.github/workflows/sync-cli-docs.yml b/.github/workflows/sync-cli-docs.yml index 3f4c620..0d6f604 100644 --- a/.github/workflows/sync-cli-docs.yml +++ b/.github/workflows/sync-cli-docs.yml @@ -29,6 +29,18 @@ jobs: - name: Regenerate CLI docs run: go generate ./docs/... + # The sync copies whatever is on disk. If regeneration changes anything, + # the tag's committed reference did not match its own command tree, and + # the copy would silently publish stale pages. Fail here rather than open + # a PR that looks authoritative. + - name: Fail if the tag's committed docs are stale + run: | + if ! git diff --quiet -- docs/ || [ -n "$(git ls-files --others --exclude-standard docs/)" ]; then + echo "::error::Committed docs do not match generated output for this ref." + git status --short -- docs/ + exit 1 + fi + - name: Checkout KeeperHub repo uses: actions/checkout@v4 with: @@ -47,6 +59,16 @@ jobs: rm -rf "$KH_DOCS/commands/"kh*.md cp "$CLI_DOCS/"kh*.md "$KH_DOCS/commands/" + # A partial copy publishes a reference that looks complete but omits + # commands entirely, which reads as "this command does not exist". + GENERATED=$(find "$CLI_DOCS" -maxdepth 1 -name 'kh*.md' | wc -l) + COPIED=$(find "$KH_DOCS/commands" -maxdepth 1 -name 'kh*.md' | wc -l) + if [ "$GENERATED" -ne "$COPIED" ]; then + echo "::error::Synced $COPIED of $GENERATED command pages." + exit 1 + fi + echo "Synced $COPIED command pages." + # Sync hand-written guides (add frontmatter for Nextra) for file in quickstart.md concepts.md; do TITLE=$(head -1 "$CLI_DOCS/$file" | sed 's/^# //') diff --git a/cmd/auth/login.go b/cmd/auth/login.go index bd2b927..382731c 100644 --- a/cmd/auth/login.go +++ b/cmd/auth/login.go @@ -41,7 +41,7 @@ func NewLoginCmd(f *cmdutil.Factory) *cobra.Command { Short: "Log in to KeeperHub", Args: cobra.NoArgs, Long: `Authenticate with KeeperHub using the device code flow. -Opens a browser to confirm a one-time code. +Prints a URL and a one-time code; open the URL in a browser to confirm it. Use --with-token to read an API key from stdin for non-interactive automation. See also: kh auth status, kh auth logout`, diff --git a/docs/doc.go b/docs/doc.go new file mode 100644 index 0000000..e907d7d --- /dev/null +++ b/docs/doc.go @@ -0,0 +1,14 @@ +// Package docs holds the generated command reference. +// +// The generator itself lives in generate.go, which carries a `//go:build +// ignore` constraint so it is not compiled into the module. That constraint is +// also why the `//go:generate` directive cannot live there: a build-excluded +// file is never scanned, so `go generate ./docs/` silently did nothing, exited +// 0, and left the CI docs check comparing an unchanged tree against itself. +// +// Keeping the directive in this compiled file is what makes `go generate +// ./docs/` regenerate the reference, and therefore what makes the docs check +// and the downstream sync to keeperhub meaningful. +package docs + +//go:generate go run generate.go diff --git a/docs/generate.go b/docs/generate.go index 805e213..4cbb7f3 100644 --- a/docs/generate.go +++ b/docs/generate.go @@ -11,7 +11,9 @@ import ( "github.com/spf13/cobra/doc" ) -//go:generate go run generate.go +// The //go:generate directive lives in doc.go, not here: this file is excluded +// from the build by the constraint above, so directives in it are never +// scanned. func main() { ios := iostreams.System() diff --git a/docs/kh.md b/docs/kh.md index 073ac5a..321d1da 100644 --- a/docs/kh.md +++ b/docs/kh.md @@ -10,6 +10,7 @@ KeeperHub CLI --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` @@ -18,19 +19,20 @@ KeeperHub CLI * [kh action](kh_action.md) - Browse available actions * [kh auth](kh_auth.md) - Authenticate with KeeperHub * [kh billing](kh_billing.md) - View billing and usage +* [kh chain](kh_chain.md) - Manage blockchain chains * [kh completion](kh_completion.md) - Generate shell completion scripts * [kh config](kh_config.md) - Manage CLI configuration * [kh doctor](kh_doctor.md) - Check CLI health * [kh execute](kh_execute.md) - Execute direct blockchain actions * [kh org](kh_org.md) - Manage organizations +* [kh plugin](kh_plugin.md) - Browse available plugins and integrations * [kh project](kh_project.md) - Manage projects -* [kh protocol](kh_protocol.md) - Browse blockchain protocols +* [kh read](kh_read.md) - Read a smart contract view function * [kh run](kh_run.md) - Monitor workflow runs -* [kh serve](kh_serve.md) - Start a server * [kh tag](kh_tag.md) - Manage tags * [kh template](kh_template.md) - Manage workflow templates * [kh update](kh_update.md) - Update kh to the latest version * [kh version](kh_version.md) - Show CLI version -* [kh wallet](kh_wallet.md) - Manage wallets +* [kh wallet](kh_wallet.md) - Manage wallets (creator-wallet REST API or agentic-wallet npm package) * [kh workflow](kh_workflow.md) - Manage workflows diff --git a/docs/kh_action.md b/docs/kh_action.md index 3759fb3..0b6c66c 100644 --- a/docs/kh_action.md +++ b/docs/kh_action.md @@ -25,6 +25,7 @@ Browse available actions ``` -H, --host string KeeperHub host (default: app.keeperhub.com) --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_action_get.md b/docs/kh_action_get.md index 03bb082..ba9ab71 100644 --- a/docs/kh_action_get.md +++ b/docs/kh_action_get.md @@ -29,6 +29,7 @@ kh action get [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_action_list.md b/docs/kh_action_list.md index 45c4544..453f037 100644 --- a/docs/kh_action_list.md +++ b/docs/kh_action_list.md @@ -30,6 +30,7 @@ kh action list [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_auth.md b/docs/kh_auth.md index f1c3bd8..cd74618 100644 --- a/docs/kh_auth.md +++ b/docs/kh_auth.md @@ -25,6 +25,7 @@ Authenticate with KeeperHub --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_auth_login.md b/docs/kh_auth_login.md index f2a8504..166f87c 100644 --- a/docs/kh_auth_login.md +++ b/docs/kh_auth_login.md @@ -5,7 +5,7 @@ Log in to KeeperHub ### Synopsis Authenticate with KeeperHub using the device code flow. -Opens a browser to confirm a one-time code. +Prints a URL and a one-time code; open the URL in a browser to confirm it. Use --with-token to read an API key from stdin for non-interactive automation. See also: kh auth status, kh auth logout diff --git a/docs/kh_auth_logout.md b/docs/kh_auth_logout.md index 9815f91..826f2a9 100644 --- a/docs/kh_auth_logout.md +++ b/docs/kh_auth_logout.md @@ -36,6 +36,7 @@ kh auth logout [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_auth_status.md b/docs/kh_auth_status.md index f5e263d..c478e58 100644 --- a/docs/kh_auth_status.md +++ b/docs/kh_auth_status.md @@ -29,6 +29,7 @@ kh auth status [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_billing.md b/docs/kh_billing.md index 99020dc..52705f9 100644 --- a/docs/kh_billing.md +++ b/docs/kh_billing.md @@ -25,6 +25,7 @@ View billing and usage ``` -H, --host string KeeperHub host (default: app.keeperhub.com) --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_billing_status.md b/docs/kh_billing_status.md index f60d7bc..7e25312 100644 --- a/docs/kh_billing_status.md +++ b/docs/kh_billing_status.md @@ -29,6 +29,7 @@ kh billing status [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_billing_usage.md b/docs/kh_billing_usage.md index 2835e39..a354949 100644 --- a/docs/kh_billing_usage.md +++ b/docs/kh_billing_usage.md @@ -30,6 +30,7 @@ kh billing usage [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_chain.md b/docs/kh_chain.md new file mode 100644 index 0000000..ad33867 --- /dev/null +++ b/docs/kh_chain.md @@ -0,0 +1,33 @@ +## kh chain + +Manage blockchain chains + +### Examples + +``` + # List supported chains + kh ch ls +``` + +### Options + +``` + -h, --help help for chain +``` + +### Options inherited from parent commands + +``` + -H, --host string KeeperHub host (default: app.keeperhub.com) + --jq string Filter JSON output with a jq expression + --json Output as JSON + --no-color Disable color output + --org string Organization ID to use (overrides default from auth) + -y, --yes Skip confirmation prompts +``` + +### SEE ALSO + +* [kh](kh.md) - KeeperHub CLI +* [kh chain list](kh_chain_list.md) - List supported blockchain chains + diff --git a/docs/kh_chain_list.md b/docs/kh_chain_list.md new file mode 100644 index 0000000..d28dab7 --- /dev/null +++ b/docs/kh_chain_list.md @@ -0,0 +1,60 @@ +## kh chain list + +List supported blockchain chains + +### Synopsis + +List supported blockchain chains. + +Note the type change if you are copying a chain id into a workflow. This +command reports "chainId" as a JSON number, but web3 workflow nodes expect +config.network as a STRING: + + kh chain list --json -> "chainId": 103 + workflow node config -> "network": "103" + +Writing the number form into a node config is accepted by the API and fails +later at execution time, so it is worth getting right up front. + +The list reflects the chains table in the target environment, which is +seeded on deploy. It is the authoritative answer for which chains are live; +the chain-config repo is only an input to that seed. + +``` +kh chain list [flags] +``` + +### Examples + +``` + # List all chains + kh ch ls + + # List chains as JSON + kh ch ls --json + + # Chain id in the string form a workflow node config expects + kh ch ls --json | jq -r '.[] | select(.name == "Solana Devnet") | .chainId | tostring' +``` + +### Options + +``` + -h, --help help for list +``` + +### Options inherited from parent commands + +``` + -H, --host string KeeperHub host (default: app.keeperhub.com) + --jq string Filter JSON output with a jq expression + --json Output as JSON + --no-color Disable color output + --org string Organization ID to use (overrides default from auth) + -y, --yes Skip confirmation prompts +``` + +### SEE ALSO + +* [kh chain](kh_chain.md) - Manage blockchain chains + diff --git a/docs/kh_completion.md b/docs/kh_completion.md index 2b2719f..e60dc3f 100644 --- a/docs/kh_completion.md +++ b/docs/kh_completion.md @@ -36,6 +36,7 @@ kh completion [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_config.md b/docs/kh_config.md index ba5484c..4ba1465 100644 --- a/docs/kh_config.md +++ b/docs/kh_config.md @@ -25,6 +25,7 @@ Manage CLI configuration --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_config_get.md b/docs/kh_config_get.md index 6cb7e64..9304fe6 100644 --- a/docs/kh_config_get.md +++ b/docs/kh_config_get.md @@ -26,6 +26,7 @@ kh config get [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_config_list.md b/docs/kh_config_list.md index e565f5a..e95e1d2 100644 --- a/docs/kh_config_list.md +++ b/docs/kh_config_list.md @@ -26,6 +26,7 @@ kh config list [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_config_set.md b/docs/kh_config_set.md index 742d3ce..025810b 100644 --- a/docs/kh_config_set.md +++ b/docs/kh_config_set.md @@ -37,6 +37,7 @@ kh config set [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_doctor.md b/docs/kh_doctor.md index 3a866eb..ba2ab0c 100644 --- a/docs/kh_doctor.md +++ b/docs/kh_doctor.md @@ -37,6 +37,7 @@ kh doctor [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_execute.md b/docs/kh_execute.md index 5d7cf55..eeda794 100644 --- a/docs/kh_execute.md +++ b/docs/kh_execute.md @@ -33,6 +33,7 @@ See also: kh r st, kh wf run --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_execute_contract-call.md b/docs/kh_execute_contract-call.md index 78d92d9..cb117fa 100644 --- a/docs/kh_execute_contract-call.md +++ b/docs/kh_execute_contract-call.md @@ -36,6 +36,7 @@ kh execute contract-call [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_execute_status.md b/docs/kh_execute_status.md index 3cb13a9..af48917 100644 --- a/docs/kh_execute_status.md +++ b/docs/kh_execute_status.md @@ -37,6 +37,7 @@ kh execute status [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_execute_transfer.md b/docs/kh_execute_transfer.md index 4d35335..4fda686 100644 --- a/docs/kh_execute_transfer.md +++ b/docs/kh_execute_transfer.md @@ -36,6 +36,7 @@ kh execute transfer [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_org.md b/docs/kh_org.md index fdd6a71..271e05b 100644 --- a/docs/kh_org.md +++ b/docs/kh_org.md @@ -25,6 +25,7 @@ Manage organizations ``` -H, --host string KeeperHub host (default: app.keeperhub.com) --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_org_list.md b/docs/kh_org_list.md index e437c02..98ad815 100644 --- a/docs/kh_org_list.md +++ b/docs/kh_org_list.md @@ -2,6 +2,16 @@ List organizations +### Synopsis + +List organizations. + +Requires a browser session. The underlying endpoint resolves a session cookie +and does not inspect the Authorization header, so this command returns 401 +under an API key regardless of the key's scope - even while 'kh workflow list' +and the rest of the CLI work normally with that same key. A 401 here is not a +sign that your key is broken. See 'kh auth-scope'. + ``` kh org list [flags] ``` @@ -29,6 +39,7 @@ kh org list [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_org_members.md b/docs/kh_org_members.md index 58305b0..23fec9d 100644 --- a/docs/kh_org_members.md +++ b/docs/kh_org_members.md @@ -2,6 +2,16 @@ List organization members +### Synopsis + +List organization members. + +Requires a browser session. This calls a Better Auth endpoint that resolves a +session cookie and does not inspect the Authorization header, so it returns 401 +under an API key regardless of the key's scope - even while the rest of the CLI +works normally with that same key. A 401 here is not a sign that your key is +broken. See 'kh auth-scope'. + ``` kh org members [flags] ``` @@ -29,6 +39,7 @@ kh org members [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_org_switch.md b/docs/kh_org_switch.md index 253652c..6a2d56b 100644 --- a/docs/kh_org_switch.md +++ b/docs/kh_org_switch.md @@ -29,6 +29,7 @@ kh org switch [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_plugin.md b/docs/kh_plugin.md new file mode 100644 index 0000000..48f970a --- /dev/null +++ b/docs/kh_plugin.md @@ -0,0 +1,37 @@ +## kh plugin + +Browse available plugins and integrations + +### Examples + +``` + # List all plugins + kh plugin ls + + # Get details for a plugin + kh plugin g aave +``` + +### Options + +``` + -h, --help help for plugin +``` + +### Options inherited from parent commands + +``` + -H, --host string KeeperHub host (default: app.keeperhub.com) + --jq string Filter JSON output with a jq expression + --json Output as JSON + --no-color Disable color output + --org string Organization ID to use (overrides default from auth) + -y, --yes Skip confirmation prompts +``` + +### SEE ALSO + +* [kh](kh.md) - KeeperHub CLI +* [kh plugin get](kh_plugin_get.md) - Get plugin details and available actions +* [kh plugin list](kh_plugin_list.md) - List available plugins and integrations + diff --git a/docs/kh_plugin_get.md b/docs/kh_plugin_get.md new file mode 100644 index 0000000..3800841 --- /dev/null +++ b/docs/kh_plugin_get.md @@ -0,0 +1,40 @@ +## kh plugin get + +Get plugin details and available actions + +``` +kh plugin get [flags] +``` + +### Examples + +``` + # Get plugin reference card + kh plugin g aave + + # Get plugin details as JSON + kh plugin g morpho --json +``` + +### Options + +``` + -h, --help help for get + --refresh Bypass local cache and fetch fresh data +``` + +### Options inherited from parent commands + +``` + -H, --host string KeeperHub host (default: app.keeperhub.com) + --jq string Filter JSON output with a jq expression + --json Output as JSON + --no-color Disable color output + --org string Organization ID to use (overrides default from auth) + -y, --yes Skip confirmation prompts +``` + +### SEE ALSO + +* [kh plugin](kh_plugin.md) - Browse available plugins and integrations + diff --git a/docs/kh_plugin_list.md b/docs/kh_plugin_list.md new file mode 100644 index 0000000..cfb0858 --- /dev/null +++ b/docs/kh_plugin_list.md @@ -0,0 +1,40 @@ +## kh plugin list + +List available plugins and integrations + +``` +kh plugin list [flags] +``` + +### Examples + +``` + # List all plugins (cached) + kh plugin ls + + # Force refresh from API + kh plugin ls --refresh +``` + +### Options + +``` + -h, --help help for list + --refresh Bypass local cache and fetch fresh data +``` + +### Options inherited from parent commands + +``` + -H, --host string KeeperHub host (default: app.keeperhub.com) + --jq string Filter JSON output with a jq expression + --json Output as JSON + --no-color Disable color output + --org string Organization ID to use (overrides default from auth) + -y, --yes Skip confirmation prompts +``` + +### SEE ALSO + +* [kh plugin](kh_plugin.md) - Browse available plugins and integrations + diff --git a/docs/kh_project.md b/docs/kh_project.md index 5b5b11b..a248b72 100644 --- a/docs/kh_project.md +++ b/docs/kh_project.md @@ -26,6 +26,7 @@ Manage projects ``` -H, --host string KeeperHub host (default: app.keeperhub.com) --no-color Disable color output + --org string Organization ID to use (overrides default from auth) ``` ### SEE ALSO diff --git a/docs/kh_project_create.md b/docs/kh_project_create.md index 09c1792..063a5e2 100644 --- a/docs/kh_project_create.md +++ b/docs/kh_project_create.md @@ -30,6 +30,7 @@ kh project create [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_project_delete.md b/docs/kh_project_delete.md index 5294613..d609424 100644 --- a/docs/kh_project_delete.md +++ b/docs/kh_project_delete.md @@ -29,6 +29,7 @@ kh project delete [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_project_get.md b/docs/kh_project_get.md index 3d6e44e..ab33cf7 100644 --- a/docs/kh_project_get.md +++ b/docs/kh_project_get.md @@ -29,6 +29,7 @@ kh project get [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_project_list.md b/docs/kh_project_list.md index b7451d9..2ea8753 100644 --- a/docs/kh_project_list.md +++ b/docs/kh_project_list.md @@ -30,6 +30,7 @@ kh project list [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_read.md b/docs/kh_read.md new file mode 100644 index 0000000..42d4ae5 --- /dev/null +++ b/docs/kh_read.md @@ -0,0 +1,59 @@ +## kh read + +Read a smart contract view function + +### Synopsis + +Call a read-only smart contract function via eth_call. + +The function signature should be in Solidity format (e.g. "balanceOf(address)"). +Arguments are positional and must match the function signature types. + +Supported argument types: address, uint256, bool, bytes32. +No auth required; uses public RPC endpoints by default. + +``` +kh read [args...] [flags] +``` + +### Examples + +``` + # Read USDT total supply + kh read 0xdAC17F958D2ee523a2206206994597C96e3cFa0e "totalSupply()" --chain 1 + + # Read ERC-20 balance + kh read 0x6B175474E89094C44Da98b954EedeAC495271d0F "balanceOf(address)" 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --chain 1 + + # Read token decimals + kh read 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 "decimals()" --chain 1 + + # Use a custom RPC endpoint + kh read 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 "decimals()" --chain 1 --rpc-url https://eth.llamarpc.com +``` + +### Options + +``` + --block string Block number or tag (default: latest) + --chain string Chain ID (required) + -h, --help help for read + --raw Output raw hex instead of decoded + --rpc-url string Override RPC endpoint +``` + +### Options inherited from parent commands + +``` + -H, --host string KeeperHub host (default: app.keeperhub.com) + --jq string Filter JSON output with a jq expression + --json Output as JSON + --no-color Disable color output + --org string Organization ID to use (overrides default from auth) + -y, --yes Skip confirmation prompts +``` + +### SEE ALSO + +* [kh](kh.md) - KeeperHub CLI + diff --git a/docs/kh_run.md b/docs/kh_run.md index e8e3eba..a30d639 100644 --- a/docs/kh_run.md +++ b/docs/kh_run.md @@ -25,6 +25,7 @@ Monitor workflow runs --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_run_cancel.md b/docs/kh_run_cancel.md index b218799..1553b70 100644 --- a/docs/kh_run_cancel.md +++ b/docs/kh_run_cancel.md @@ -29,6 +29,7 @@ kh run cancel [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_run_logs.md b/docs/kh_run_logs.md index 3278b24..dbbbdd1 100644 --- a/docs/kh_run_logs.md +++ b/docs/kh_run_logs.md @@ -29,6 +29,7 @@ kh run logs [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_run_status.md b/docs/kh_run_status.md index 88d0d0e..15f32f8 100644 --- a/docs/kh_run_status.md +++ b/docs/kh_run_status.md @@ -38,6 +38,7 @@ kh run status [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_tag.md b/docs/kh_tag.md index 7fac773..5d12b76 100644 --- a/docs/kh_tag.md +++ b/docs/kh_tag.md @@ -26,6 +26,7 @@ Manage tags ``` -H, --host string KeeperHub host (default: app.keeperhub.com) --no-color Disable color output + --org string Organization ID to use (overrides default from auth) ``` ### SEE ALSO diff --git a/docs/kh_tag_create.md b/docs/kh_tag_create.md index 60bfb38..f74f557 100644 --- a/docs/kh_tag_create.md +++ b/docs/kh_tag_create.md @@ -30,6 +30,7 @@ kh tag create [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_tag_delete.md b/docs/kh_tag_delete.md index ba4ba39..d30104a 100644 --- a/docs/kh_tag_delete.md +++ b/docs/kh_tag_delete.md @@ -29,6 +29,7 @@ kh tag delete [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_tag_get.md b/docs/kh_tag_get.md index b6b8af8..596710c 100644 --- a/docs/kh_tag_get.md +++ b/docs/kh_tag_get.md @@ -29,6 +29,7 @@ kh tag get [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_tag_list.md b/docs/kh_tag_list.md index cb0c95a..484bf19 100644 --- a/docs/kh_tag_list.md +++ b/docs/kh_tag_list.md @@ -30,6 +30,7 @@ kh tag list [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_template.md b/docs/kh_template.md index 78a7ee8..cf7bbd5 100644 --- a/docs/kh_template.md +++ b/docs/kh_template.md @@ -25,6 +25,7 @@ Manage workflow templates ``` -H, --host string KeeperHub host (default: app.keeperhub.com) --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_template_deploy.md b/docs/kh_template_deploy.md index 991a8bf..a9415c5 100644 --- a/docs/kh_template_deploy.md +++ b/docs/kh_template_deploy.md @@ -30,6 +30,7 @@ kh template deploy [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_template_list.md b/docs/kh_template_list.md index 8814252..f6fc49c 100644 --- a/docs/kh_template_list.md +++ b/docs/kh_template_list.md @@ -3,7 +3,7 @@ List workflow templates ``` -kh template list [flags] +kh template list [query] [flags] ``` ### Examples @@ -12,6 +12,10 @@ kh template list [flags] # List featured templates kh tp ls + # Search templates by keyword + kh tp ls defi + kh tp ls --query monitor + # List templates as JSON kh tp ls --json ``` @@ -19,7 +23,8 @@ kh template list [flags] ### Options ``` - -h, --help help for list + -h, --help help for list + -q, --query string Filter templates by name or description ``` ### Options inherited from parent commands @@ -29,6 +34,7 @@ kh template list [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_update.md b/docs/kh_update.md index 68702cb..963e6a9 100644 --- a/docs/kh_update.md +++ b/docs/kh_update.md @@ -34,6 +34,7 @@ kh update [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_version.md b/docs/kh_version.md index 0edf2c7..c7954a6 100644 --- a/docs/kh_version.md +++ b/docs/kh_version.md @@ -26,6 +26,7 @@ kh version [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_wallet.md b/docs/kh_wallet.md index d6e4f24..61940a8 100644 --- a/docs/kh_wallet.md +++ b/docs/kh_wallet.md @@ -1,15 +1,33 @@ ## kh wallet -Manage wallets +Manage wallets (creator-wallet REST API or agentic-wallet npm package) + +### Synopsis + +Manage wallets. + +Creator wallet (REST): + kh w balance show creator-wallet on-chain balances via KeeperHub REST API + kh w tokens list supported tokens + +Agentic wallet (thin wrappers around npx @keeperhub/wallet): + kh w add provision a new agentic wallet (no account required) + kh w info print agentic subOrgId + walletAddress + kh w fund print Coinbase Onramp URL + Tempo deposit address + kh w link link agentic wallet to a KeeperHub account (needs KH_SESSION_COOKIE) + kh w feedback submit ERC-8004 feedback for a workflow execution this wallet paid for ### Examples ``` - # Show wallet balance + # Creator wallet balance (REST): kh w balance - # List supported tokens - kh w tokens + # Provision an agentic wallet (npx wrapper): + kh w add + + # Check balance on the agentic wallet: + npx @keeperhub/wallet balance ``` ### Options @@ -25,12 +43,18 @@ Manage wallets ``` -H, --host string KeeperHub host (default: app.keeperhub.com) --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` ### SEE ALSO * [kh](kh.md) - KeeperHub CLI +* [kh wallet add](kh_wallet_add.md) - Provision a new agentic wallet (no KeeperHub account required) * [kh wallet balance](kh_wallet_balance.md) - Show wallet balance +* [kh wallet feedback](kh_wallet_feedback.md) - Submit ERC-8004 feedback for a workflow execution this wallet paid for +* [kh wallet fund](kh_wallet_fund.md) - Print Coinbase Onramp URL (Base USDC) and Tempo deposit address for the agentic wallet +* [kh wallet info](kh_wallet_info.md) - Print subOrgId and walletAddress from local agentic wallet config +* [kh wallet link](kh_wallet_link.md) - Link the agentic wallet to a KeeperHub account (requires KH_SESSION_COOKIE) * [kh wallet tokens](kh_wallet_tokens.md) - List wallet tokens diff --git a/docs/kh_wallet_add.md b/docs/kh_wallet_add.md new file mode 100644 index 0000000..2663c21 --- /dev/null +++ b/docs/kh_wallet_add.md @@ -0,0 +1,37 @@ +## kh wallet add + +Provision a new agentic wallet (no KeeperHub account required) + +### Synopsis + +Provision a new agentic wallet by calling POST /api/agentic-wallet/provision. + +This is a thin wrapper around `npx @keeperhub/wallet add` -- the npm package is the +canonical tool. Writes {subOrgId, walletAddress, hmacSecret} to ~/.keeperhub/wallet.json +(chmod 0o600) and prints subOrgId + walletAddress (hmacSecret is NEVER printed). + +``` +kh wallet add [flags] +``` + +### Options + +``` + -h, --help help for add +``` + +### Options inherited from parent commands + +``` + -H, --host string KeeperHub host (default: app.keeperhub.com) + --jq string Filter JSON output with a jq expression + --json Output as JSON + --no-color Disable color output + --org string Organization ID to use (overrides default from auth) + -y, --yes Skip confirmation prompts +``` + +### SEE ALSO + +* [kh wallet](kh_wallet.md) - Manage wallets (creator-wallet REST API or agentic-wallet npm package) + diff --git a/docs/kh_wallet_balance.md b/docs/kh_wallet_balance.md index 4857ab1..4e444ee 100644 --- a/docs/kh_wallet_balance.md +++ b/docs/kh_wallet_balance.md @@ -30,10 +30,11 @@ kh wallet balance [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` ### SEE ALSO -* [kh wallet](kh_wallet.md) - Manage wallets +* [kh wallet](kh_wallet.md) - Manage wallets (creator-wallet REST API or agentic-wallet npm package) diff --git a/docs/kh_wallet_feedback.md b/docs/kh_wallet_feedback.md new file mode 100644 index 0000000..4fcb6ce --- /dev/null +++ b/docs/kh_wallet_feedback.md @@ -0,0 +1,56 @@ +## kh wallet feedback + +Submit ERC-8004 feedback for a workflow execution this wallet paid for + +### Synopsis + +Submit ERC-8004 ReputationRegistry feedback for a workflow execution this +wallet paid for. Signs giveFeedback() via Turnkey and broadcasts on Ethereum +mainnet via the KeeperHub server proxy. Caller wallet pays gas natively +(~$0.05-2 per call at typical mainnet gas). + +Thin wrapper around `npx @keeperhub/wallet feedback`. Defaults to rating +KeeperHub's own ERC-8004 agent (id 31875 on Ethereum); use --agent-id to rate +any other agent. + +``` +kh wallet feedback [flags] +``` + +### Examples + +``` + # 5-star rating for an execution this wallet paid for + kh w feedback --execution-id c5ybokpmwxi7kiau5wxja --value 5 + + # 4.5-star rating with a comment + kh w feedback --execution-id c5ybokpmwxi7kiau5wxja --value 45 --decimals 1 --comment "very helpful" +``` + +### Options + +``` + --agent-id string rated agent NFT id (uint256 decimal); defaults to KeeperHub agent 31875 + --chain-id string agent chain id; defaults to 1 (Ethereum mainnet) + --comment string optional plaintext comment included in the feedbackURI JSON + --decimals string decimals for value (0..18); 0 for integer scores, 1 for 0.1-step (default 0) + --execution-id string workflow execution id (from a previous call_workflow response) (required) + -h, --help help for feedback + --value string raw int128 rating value, e.g. 5 with --decimals 0 for a 5-star rating (required) +``` + +### Options inherited from parent commands + +``` + -H, --host string KeeperHub host (default: app.keeperhub.com) + --jq string Filter JSON output with a jq expression + --json Output as JSON + --no-color Disable color output + --org string Organization ID to use (overrides default from auth) + -y, --yes Skip confirmation prompts +``` + +### SEE ALSO + +* [kh wallet](kh_wallet.md) - Manage wallets (creator-wallet REST API or agentic-wallet npm package) + diff --git a/docs/kh_wallet_fund.md b/docs/kh_wallet_fund.md new file mode 100644 index 0000000..4d5fcef --- /dev/null +++ b/docs/kh_wallet_fund.md @@ -0,0 +1,36 @@ +## kh wallet fund + +Print Coinbase Onramp URL (Base USDC) and Tempo deposit address for the agentic wallet + +### Synopsis + +Print a Coinbase Onramp URL for Base USDC funding plus the Tempo deposit address. + +Thin wrapper around `npx @keeperhub/wallet fund`. No HTTP calls, no browser launch -- +prints copy-paste instructions only. + +``` +kh wallet fund [flags] +``` + +### Options + +``` + -h, --help help for fund +``` + +### Options inherited from parent commands + +``` + -H, --host string KeeperHub host (default: app.keeperhub.com) + --jq string Filter JSON output with a jq expression + --json Output as JSON + --no-color Disable color output + --org string Organization ID to use (overrides default from auth) + -y, --yes Skip confirmation prompts +``` + +### SEE ALSO + +* [kh wallet](kh_wallet.md) - Manage wallets (creator-wallet REST API or agentic-wallet npm package) + diff --git a/docs/kh_wallet_info.md b/docs/kh_wallet_info.md new file mode 100644 index 0000000..8ab937f --- /dev/null +++ b/docs/kh_wallet_info.md @@ -0,0 +1,35 @@ +## kh wallet info + +Print subOrgId and walletAddress from local agentic wallet config + +### Synopsis + +Print subOrgId and walletAddress from ~/.keeperhub/wallet.json. + +Thin wrapper around `npx @keeperhub/wallet info`. Exits non-zero if the config is missing. + +``` +kh wallet info [flags] +``` + +### Options + +``` + -h, --help help for info +``` + +### Options inherited from parent commands + +``` + -H, --host string KeeperHub host (default: app.keeperhub.com) + --jq string Filter JSON output with a jq expression + --json Output as JSON + --no-color Disable color output + --org string Organization ID to use (overrides default from auth) + -y, --yes Skip confirmation prompts +``` + +### SEE ALSO + +* [kh wallet](kh_wallet.md) - Manage wallets (creator-wallet REST API or agentic-wallet npm package) + diff --git a/docs/kh_wallet_link.md b/docs/kh_wallet_link.md new file mode 100644 index 0000000..5582a8e --- /dev/null +++ b/docs/kh_wallet_link.md @@ -0,0 +1,38 @@ +## kh wallet link + +Link the agentic wallet to a KeeperHub account (requires KH_SESSION_COOKIE) + +### Synopsis + +Link the current agentic wallet to your KeeperHub account by calling POST /api/agentic-wallet/link. + +Thin wrapper around `npx @keeperhub/wallet link`. Requires the KH_SESSION_COOKIE env var +set to a valid kh session cookie (sign in at app.keeperhub.com, copy the session cookie, export it). + +v0.1.0 does not launch a browser session handshake; this env-var contract matches the npm CLI. + +``` +kh wallet link [flags] +``` + +### Options + +``` + -h, --help help for link +``` + +### Options inherited from parent commands + +``` + -H, --host string KeeperHub host (default: app.keeperhub.com) + --jq string Filter JSON output with a jq expression + --json Output as JSON + --no-color Disable color output + --org string Organization ID to use (overrides default from auth) + -y, --yes Skip confirmation prompts +``` + +### SEE ALSO + +* [kh wallet](kh_wallet.md) - Manage wallets (creator-wallet REST API or agentic-wallet npm package) + diff --git a/docs/kh_wallet_tokens.md b/docs/kh_wallet_tokens.md index c405cbb..3e3ba3a 100644 --- a/docs/kh_wallet_tokens.md +++ b/docs/kh_wallet_tokens.md @@ -31,10 +31,11 @@ kh wallet tokens [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` ### SEE ALSO -* [kh wallet](kh_wallet.md) - Manage wallets +* [kh wallet](kh_wallet.md) - Manage wallets (creator-wallet REST API or agentic-wallet npm package) diff --git a/docs/kh_workflow.md b/docs/kh_workflow.md index d6acd5d..c4c79e9 100644 --- a/docs/kh_workflow.md +++ b/docs/kh_workflow.md @@ -25,16 +25,20 @@ Manage workflows ``` -H, --host string KeeperHub host (default: app.keeperhub.com) --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` ### SEE ALSO * [kh](kh.md) - KeeperHub CLI +* [kh workflow create](kh_workflow_create.md) - Create a workflow * [kh workflow delete](kh_workflow_delete.md) - Delete a workflow * [kh workflow get](kh_workflow_get.md) - Get a workflow * [kh workflow go-live](kh_workflow_go-live.md) - Publish a workflow * [kh workflow list](kh_workflow_list.md) - List workflows * [kh workflow pause](kh_workflow_pause.md) - Pause a workflow +* [kh workflow resume](kh_workflow_resume.md) - Resume a paused workflow * [kh workflow run](kh_workflow_run.md) - Run a workflow +* [kh workflow update](kh_workflow_update.md) - Update a workflow diff --git a/docs/kh_workflow_create.md b/docs/kh_workflow_create.md new file mode 100644 index 0000000..c40bbe5 --- /dev/null +++ b/docs/kh_workflow_create.md @@ -0,0 +1,75 @@ +## kh workflow create + +Create a workflow + +### Synopsis + +Create a workflow. + +Nodes and edges can be supplied two ways, and the two take different shapes: + + --nodes-file FILE a JSON OBJECT: {"nodes": [...], "edges": [...]} + --nodes / --edges bare JSON ARRAYS, passed separately + +Inline flags override the file when both are given. 'kh workflow update' accepts +only --nodes-file, so a file is the portable choice if you intend to edit the +workflow later. + +New workflows are created DISABLED. There is no --enabled flag; enable the +workflow in the web app, or PATCH "enabled": true against the API directly. + +Node config is only lightly checked on the way in. An integrationId that +matches no integration is accepted (the API treats unknown ids as stale-but- +savable references), and "network" and "actionType" are not validated at all. +A successful create is not evidence that the workflow runs - misconfiguration +surfaces at execution time. + +``` +kh workflow create [flags] +``` + +### Examples + +``` + # Create an empty workflow + kh wf create --name "My Workflow" + + # Create with nodes from a JSON file - the file is an object, not an array: + # {"nodes": [ ... ], "edges": [ ... ]} + kh wf create --name "DeFi Monitor" --nodes-file workflow.json + + # Create with inline JSON nodes - these flags take bare arrays + kh wf create --name "Test" --nodes '[{"id":"t1","type":"trigger","position":{"x":0,"y":0},"data":{"type":"trigger","config":{"triggerType":"Manual"}}}]' + + # Create inside a project and label it with a tag + kh wf create --name "Payouts" --project proj_123 --tag tag_456 +``` + +### Options + +``` + --description string Workflow description + --edges string Inline JSON array of edges (overrides --nodes-file) + -h, --help help for create + --name string Workflow name (required) + --nodes string Inline JSON array of nodes (overrides --nodes-file) + --nodes-file string Path to a JSON file shaped {"nodes": [...], "edges": [...]} + --project string Project ID to assign the workflow to + --tag string Tag ID to label the workflow +``` + +### Options inherited from parent commands + +``` + -H, --host string KeeperHub host (default: app.keeperhub.com) + --jq string Filter JSON output with a jq expression + --json Output as JSON + --no-color Disable color output + --org string Organization ID to use (overrides default from auth) + -y, --yes Skip confirmation prompts +``` + +### SEE ALSO + +* [kh workflow](kh_workflow.md) - Manage workflows + diff --git a/docs/kh_workflow_delete.md b/docs/kh_workflow_delete.md index df18c83..1fcaf9c 100644 --- a/docs/kh_workflow_delete.md +++ b/docs/kh_workflow_delete.md @@ -34,8 +34,10 @@ kh workflow delete [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) ``` ### SEE ALSO * [kh workflow](kh_workflow.md) - Manage workflows + diff --git a/docs/kh_workflow_get.md b/docs/kh_workflow_get.md index 5286f3d..78d8ffd 100644 --- a/docs/kh_workflow_get.md +++ b/docs/kh_workflow_get.md @@ -20,6 +20,7 @@ kh workflow get [flags] ``` -h, --help help for get + --web Open the workflow in the browser ``` ### Options inherited from parent commands @@ -29,6 +30,7 @@ kh workflow get [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_workflow_go-live.md b/docs/kh_workflow_go-live.md index 5158bfb..a3797ea 100644 --- a/docs/kh_workflow_go-live.md +++ b/docs/kh_workflow_go-live.md @@ -31,6 +31,7 @@ kh workflow go-live [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_workflow_list.md b/docs/kh_workflow_list.md index 9c02879..a45cdbd 100644 --- a/docs/kh_workflow_list.md +++ b/docs/kh_workflow_list.md @@ -14,13 +14,19 @@ kh workflow list [flags] # List with a higher limit kh wf ls --limit 5 + + # List workflows in a project or with a tag + kh wf ls --project proj_123 + kh wf ls --tag tag_456 ``` ### Options ``` - -h, --help help for list - --limit int Maximum number of workflows to list (default 30) + -h, --help help for list + --limit int Maximum number of workflows to list (default 30) + --project string Filter workflows by project ID + --tag string Filter workflows by tag ID ``` ### Options inherited from parent commands @@ -30,6 +36,7 @@ kh workflow list [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_workflow_pause.md b/docs/kh_workflow_pause.md index acb8f04..f75918a 100644 --- a/docs/kh_workflow_pause.md +++ b/docs/kh_workflow_pause.md @@ -30,6 +30,7 @@ kh workflow pause [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) ``` ### SEE ALSO diff --git a/docs/kh_workflow_resume.md b/docs/kh_workflow_resume.md new file mode 100644 index 0000000..d6a740a --- /dev/null +++ b/docs/kh_workflow_resume.md @@ -0,0 +1,39 @@ +## kh workflow resume + +Resume a paused workflow + +``` +kh workflow resume [flags] +``` + +### Examples + +``` + # Resume a workflow (will prompt for confirmation) + kh wf resume abc123 + + # Resume without prompting + kh wf resume abc123 --yes +``` + +### Options + +``` + -h, --help help for resume + -y, --yes Skip confirmation prompt +``` + +### Options inherited from parent commands + +``` + -H, --host string KeeperHub host (default: app.keeperhub.com) + --jq string Filter JSON output with a jq expression + --json Output as JSON + --no-color Disable color output + --org string Organization ID to use (overrides default from auth) +``` + +### SEE ALSO + +* [kh workflow](kh_workflow.md) - Manage workflows + diff --git a/docs/kh_workflow_run.md b/docs/kh_workflow_run.md index 10c7b24..35ca610 100644 --- a/docs/kh_workflow_run.md +++ b/docs/kh_workflow_run.md @@ -39,6 +39,7 @@ kh workflow run [flags] --jq string Filter JSON output with a jq expression --json Output as JSON --no-color Disable color output + --org string Organization ID to use (overrides default from auth) -y, --yes Skip confirmation prompts ``` diff --git a/docs/kh_workflow_update.md b/docs/kh_workflow_update.md new file mode 100644 index 0000000..c3972ab --- /dev/null +++ b/docs/kh_workflow_update.md @@ -0,0 +1,73 @@ +## kh workflow update + +Update a workflow + +### Synopsis + +Update a workflow. + +Nodes and edges can only be supplied as a file. Unlike 'kh workflow create', +there are no inline --nodes / --edges flags here. + +The file is a JSON OBJECT holding both keys, not a bare array of nodes: + + {"nodes": [...], "edges": [...]} + +Both keys are sent together, so --nodes-file replaces the whole graph. To +change one node, fetch the current definition first: + + kh workflow get --json > workflow.json + +Node config is only lightly checked on the way in. An integrationId that +matches no integration is accepted (the API treats unknown ids as stale-but- +savable references), and "network" and "actionType" are not validated at all. +A successful update is not evidence that the workflow runs - misconfiguration +surfaces at execution time. + +``` +kh workflow update [flags] +``` + +### Examples + +``` + # Update workflow name + kh wf update abc123 --name "New Name" + + # Update nodes from file - the file is an object, not an array: + # {"nodes": [ ... ], "edges": [ ... ]} + kh wf update abc123 --nodes-file workflow.json + + # Assign the workflow to a project and tag + kh wf update abc123 --project proj_123 --tag tag_456 + + # Remove the workflow from its project (pass an empty value) + kh wf update abc123 --project "" +``` + +### Options + +``` + --description string New workflow description + -h, --help help for update + --name string New workflow name + --nodes-file string Path to a JSON file shaped {"nodes": [...], "edges": [...]}; replaces the whole graph + --project string Project ID to assign (empty value unassigns) + --tag string Tag ID to assign (empty value unassigns) +``` + +### Options inherited from parent commands + +``` + -H, --host string KeeperHub host (default: app.keeperhub.com) + --jq string Filter JSON output with a jq expression + --json Output as JSON + --no-color Disable color output + --org string Organization ID to use (overrides default from auth) + -y, --yes Skip confirmation prompts +``` + +### SEE ALSO + +* [kh workflow](kh_workflow.md) - Manage workflows + diff --git a/internal/auth/device.go b/internal/auth/device.go index ec9d65f..6b82be2 100644 --- a/internal/auth/device.go +++ b/internal/auth/device.go @@ -128,7 +128,9 @@ func pollDeviceToken(ctx context.Context, baseURL, deviceCode string, interval t case "slow_down": interval += 5 * time.Second case "expired_token": - return "", errors.New("device code expired, run 'kh auth login --no-browser' again") + // --no-browser does not exist; suggesting it sent users looking for + // a flag the CLI has never had. + return "", errors.New("device code expired, run 'kh auth login' again") case "access_denied": return "", errors.New("authentication denied") default: