diff --git a/CLAUDE.md b/CLAUDE.md index 5474f41c..533df481 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -295,7 +295,7 @@ Full author checklist: see `CONTRIBUTING.md` > "Releasing a beta (pre-release) v ## Claude Code Plugin -The plugin lives here in `plugins/kbagent/` and is **published through `keboola/ai-kit`**. It exposes four AI surfaces: a CLI (`kbagent`), a skill (`kbagent`), a slash command (`/keboola`), and a specialist subagent (`keboola-expert`). All are namespaced under `kbagent:`. +The plugin lives here in `plugins/kbagent/` and is **published through `keboola/ai-kit`**. It exposes: a CLI (`kbagent`), three skills (`kbagent`, `kbagent-cicd-migration`, `kbagent-promotion-pipeline`), three slash commands (`/kbagent:setup`, `/keboola`, `/kbagent:review`), and two specialist subagents (`keboola-expert`, `kbagent-pr-reviewer`). All are namespaced under `kbagent:`. `/kbagent:setup` is the documented one-command first-run path (install CLI -> connect project -> `doctor`); it runs in the main context and spawns no subagent. **Source here, publication there.** The source stays in this repo because four CI gates validate it against the live command tree (`make skill-gen` / `make skill-check`, `scripts/sync_version.py`, `scripts/check_command_sync.py`, `make version-check`) -- none of which exist in ai-kit. What ai-kit owns is the *catalogue*: its `keboola-claude-kit` marketplace carries an external `git-subdir` entry pointing at `plugins/kbagent` in this repo, pinned to a release tag. Keboola has ONE Claude Code marketplace, and it is not this one. @@ -303,6 +303,7 @@ The plugin lives here in `plugins/kbagent/` and is **published through `keboola/ ``` /plugin marketplace add keboola/ai-kit /plugin install kbagent@keboola-claude-kit +/kbagent:setup ``` **The sync mechanism** is the `ai-kit-marketplace` job in `.github/workflows/release-kbagent.yml`: on every stable tag it rewrites the kbagent entry's `version` + `source.ref` in ai-kit and opens a PR there (a PR, not a push -- ai-kit's evals must see it). It needs `secrets.AI_KIT_TOKEN` in the `release` environment. No-op safe: an entry already at this version opens nothing. @@ -320,14 +321,20 @@ plugins/kbagent/ CLAUDE.md # Operational guidance for Claude Code main agents agents/ keboola-expert.md # Specialist subagent system prompt (HIGHEST silent-drift risk) + kbagent-pr-reviewer.md # Read-only PR-review subagent system prompt commands/ + setup.md # /kbagent:setup slash command (one-command first-run setup) keboola.md # /keboola slash command - skills/kbagent/ - SKILL.md # Trigger rules + auto-generated decision table - references/ - commands-reference.md # Per-command notes (hand-maintained) - gotchas.md # Response parsing + (since vX.Y.Z) behavior log - -workflow.md # One file per workflow (workspace, branch, sync, ...) + review.md # /kbagent:review slash command + skills/ + kbagent/ + SKILL.md # Trigger rules + auto-generated decision table + references/ + commands-reference.md # Per-command notes (hand-maintained) + gotchas.md # Response parsing + (since vX.Y.Z) behavior log + -workflow.md # One file per workflow (workspace, branch, sync, ...) + kbagent-cicd-migration/ # CI/CD migration skill + kbagent-promotion-pipeline/ # Promotion-pipeline skill ``` `SKILL.md` instructs Claude to run `kbagent context` as its first step, which dynamically loads the full CLI documentation. That keeps command *signatures* in sync automatically -- but it does **not** save the agent's tool-selection matrix, the gotchas log, or the version-gate examples in `keboola-expert.md`. Those are static and must be updated by hand whenever the CLI changes. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 881c2fe1..bbd712df 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -385,7 +385,7 @@ before the PR is mergeable. - [ ] **`plugins/kbagent/skills/kbagent/references/gotchas.md`** -- if the command's behavior is non-obvious, add an entry tagged with a version. In a feature PR that version is not known yet (the PR does not bump the version), so tag with the literal placeholder `(since vNEXT)` -- the release PR replaces every `vNEXT` with the version actually being released. Never guess a numeric version: `make version-gate-check` (per-PR CI) rejects any `(since vX.Y.Z)` whose version has no `changelog.py` entry. The version tag is **non-optional**; gotchas without versions are how AI agents end up recommending behavior that does not exist on older kbagent installs. - [ ] **`plugins/kbagent/skills/kbagent/references/-workflow.md`** -- create a new file if the command introduces a new workflow or topic area (existing examples: `workspace-workflow.md`, `branch-workflow.md`, `sync-workflow.md`, `storage-files-workflow.md`, `storage-types-workflow.md`). Single-command additions go into an existing workflow file. - [ ] **`plugins/kbagent/.claude-plugin/CLAUDE.md`** -- only update when the high-level delegation strategy changes (e.g. new "when NOT to delegate" cases). Most command additions do not touch this. -- [ ] **`plugins/kbagent/commands/keboola.md`** -- only update if the `/keboola` slash-command UX changes. Most command additions do not touch this. +- [ ] **`plugins/kbagent/commands/*.md`** -- only update if a slash-command UX changes (`/keboola`, `/kbagent:setup`, `/kbagent:review`). Most command additions do not touch these. Adding a *new* slash-command file has its own follow-through list -- see the [Plugin synchronization map](#plugin-synchronization-map) row. ### Tests (mandatory!) @@ -466,7 +466,7 @@ release checklist below. | **`keboola/ai-kit` -> `.claude-plugin/marketplace.json`** (ANOTHER REPO) | Every stable release -- this is where the plugin is actually published (`keboola-claude-kit`, an external `git-subdir` entry pinned to the release tag). Automated: the `ai-kit-marketplace` job in `.github/workflows/release-kbagent.yml` rewrites `version` + `source.ref` and opens a PR against keboola/ai-kit. **Merging that PR is what ships the release to plugin users** -- a green release here does not move them | NO -- nothing in this repo can see ai-kit's catalogue. Check the opened PR after every release; if `secrets.AI_KIT_TOKEN` is missing or expired the job fails and no PR appears | | `plugins/kbagent/.claude-plugin/CLAUDE.md` | Changing delegation strategy / when-to-delegate rules | NO | | `plugins/kbagent/agents/keboola-expert.md` | New write/destructive command **group** (one matrix row per group, not per command -- file has a hard 70 000 B prompt budget); new minimum-version requirement (Rule 6 VERSION GATE); behavior change (gotchas) | NO -- **highest silent-drift risk** | -| `plugins/kbagent/commands/keboola.md` | `/keboola` slash-command UX change (rare) | NO | +| `plugins/kbagent/commands/*.md` (`setup.md`, `keboola.md`, `review.md`) | Slash-command UX change (rare). **Adding a new slash-command file** also needs: the surfaces list + "For Claude Code users" block in `plugins/kbagent/.claude-plugin/CLAUDE.md`, `skills/kbagent/SKILL.md` prose if it changes the documented setup/usage path, and the user-facing flow in `README.md`, `docs/TUTORIAL.md`, `commands/context.py` `AGENT_CONTEXT` and `install.sh`'s "Next steps" | NO -- no CI gate or test reads `commands/*.md` at all | | `plugins/kbagent/skills/kbagent/SKILL.md` -- table | Auto-generated by `make skill-gen` | YES (`make skill-check`; pre-commit auto-stages) | | `plugins/kbagent/skills/kbagent/SKILL.md` -- description / rules / workflow links | New topic area in `description` triggers; new workflow file added to bottom table | NO | | `plugins/kbagent/skills/kbagent/references/commands-reference.md` | Adding/removing/renaming commands; flag changes | NO | diff --git a/README.md b/README.md index b64fe712..4b8fb40e 100644 --- a/README.md +++ b/README.md @@ -100,8 +100,11 @@ This CLI is built AI-first. Every command outputs structured JSON (`--json`), er ``` /plugin marketplace add keboola/ai-kit /plugin install kbagent@keboola-claude-kit +/kbagent:setup ``` +`/kbagent:setup` is the whole rest of the setup in one command: it installs the `kbagent` CLI if you don't have it, connects a Keboola project (browser login, so there is no token to paste; on a headless host it falls back to an account login from the environment, then to a static token), and verifies the result with `kbagent doctor`. Every step is conditional, so re-running it after a partial setup just fills the gaps. + Then either let the `kbagent` skill auto-trigger from natural prompts, or delegate explicitly with `/keboola ` -- the slash command spawns a `kbagent:keboola-expert` subagent with fresh context, hard rules (fresh fetch, dry-run first, prefer CLI over raw REST, version gate), and a JSON verification payload. See [docs/TUTORIAL.md §6](docs/TUTORIAL.md#6-using-the-agent-and-slash-commands). **Any other agent** -- just tell it to run `kbagent context` and it gets the full command reference. diff --git a/docs/TUTORIAL.md b/docs/TUTORIAL.md index 0bfa0ffb..27055e57 100644 --- a/docs/TUTORIAL.md +++ b/docs/TUTORIAL.md @@ -309,11 +309,24 @@ In Claude Code, run: ``` /plugin marketplace add keboola/ai-kit /plugin install kbagent@keboola-claude-kit +/kbagent:setup ``` Claude Code clones the marketplace and drops the plugin into `~/.claude/plugins/cache/keboola-claude-kit/kbagent//`. +`/kbagent:setup` then does everything else in one command: installs the +`kbagent` CLI if it is missing (handling the installer's PATH caveat), +connects a project via `kbagent auth login --register-projects` (browser +login -- nothing to paste; on a headless host it drops to `kbagent auth +login-password` when `KBC_LOGIN_EMAIL`/`KBC_LOGIN_PASSWORD` are already in +the environment, and only then to a `kbagent project add` static token -- +which is also the direct answer for a surface no browser session can serve, +since a password login yields the same restricted session), +and finishes with `kbagent doctor`, interpreting the result for you. Each +step runs only if its check fails, so it is safe to re-run at any point +-- including if you already followed §1-§4 by hand. + ### Verify Outside Claude Code: @@ -337,6 +350,7 @@ you to run `/plugin update kbagent` in Claude Code. | Component | What it does | |---|---| | `kbagent` skill | Loaded into the main agent when it recognises Keboola-related prompts. 10 rules + a decision table mapping goals to commands. | +| `/kbagent:setup` slash command | One-command first-run setup: install the CLI, connect a project, verify with `doctor`. Idempotent. | | `/keboola ` slash command | Explicitly delegates a Keboola task to the specialist subagent (see §6). | | `kbagent:keboola-expert` subagent | Fresh-context specialist with non-negotiable rules, tool matrix, inline gotchas, and a JSON verification payload output contract. | | Plugin-level `CLAUDE.md` | Instructs the main agent *when* to delegate vs. handle inline. | diff --git a/install.sh b/install.sh index 6c392d0a..74113c5a 100755 --- a/install.sh +++ b/install.sh @@ -258,6 +258,10 @@ printf ' %s%s%s %s%s%s %s %s\n' "$GREEN" "$CHECK" "$RESET" "$BOLD" "$ver_str" printf ' %sno sudo required%s\n' "$DIM" "$RESET" >&2 info "" printf ' %sNext steps%s\n' "$BOLD" "$RESET" >&2 +printf ' %sIn Claude Code:%s %s/kbagent:setup%s %s# connect + verify in one command%s\n' "$DIM" "$RESET" "$BOLD" "$RESET" "$DIM" "$RESET" >&2 +printf ' %s(needs the plugin:%s %skbagent doctor%s %sprints the exact /plugin commands)%s\n' "$DIM" "$RESET" "$BOLD" "$RESET" "$DIM" "$RESET" >&2 +info "" +printf ' %sOr do it by hand%s\n' "$BOLD" "$RESET" >&2 printf ' %skbagent project add%s --project myproject \\\n' "$BOLD" "$RESET" >&2 printf ' --url https://connection.keboola.com --token YOUR_TOKEN %s# connect a project%s\n' "$DIM" "$RESET" >&2 printf ' %skbagent --help%s %s# see everything you can do%s\n' "$BOLD" "$RESET" "$DIM" "$RESET" >&2 diff --git a/plugins/kbagent/.claude-plugin/CLAUDE.md b/plugins/kbagent/.claude-plugin/CLAUDE.md index e152aa5d..10d6c89a 100644 --- a/plugins/kbagent/.claude-plugin/CLAUDE.md +++ b/plugins/kbagent/.claude-plugin/CLAUDE.md @@ -1,9 +1,15 @@ # kbagent plugin — operational guidance -This plugin exposes a CLI (`kbagent`), a skill (`kbagent`), two slash -commands (`/keboola`, `/kbagent:review`), and two specialist subagents -(`keboola-expert`, `kbagent-pr-reviewer`). All are namespaced under -`kbagent:`. The two subagents serve disjoint domains: +This plugin exposes a CLI (`kbagent`), three skills (`kbagent`, +`kbagent-cicd-migration`, `kbagent-promotion-pipeline`), three slash +commands (`/kbagent:setup`, `/keboola`, `/kbagent:review`), and two +specialist subagents (`keboola-expert`, `kbagent-pr-reviewer`). All are +namespaced under `kbagent:`. + +`/kbagent:setup` is the first-run entry point: it installs the CLI if +missing, connects a project, and verifies with `kbagent doctor` -- every +step conditional, so it is safe to re-run. It runs in the main context and +spawns no subagent. The two subagents serve disjoint domains: | Subagent | Use for | Slash command | Trigger phrases | |---|---|---|---| @@ -124,7 +130,12 @@ When the subagent returns: ## For Claude Code users -- Install the kbagent CLI: `uv tool install git+https://github.com/keboola/cli` +- **Start here: run `/kbagent:setup`.** One command -- it installs the + kbagent CLI if it is missing, connects a Keboola project (browser + login, falling back to `auth login-password` from the environment and + then a static token, per the order above), and verifies the result with + `kbagent doctor`. Idempotent, so re-running it after a partial setup + only fills the gaps. - Initialize a project workspace: `kbagent init --from-global` (writes `.kbagent/config.json` whose first field is a `_warning` steering any LLM that reads the file away from direct REST calls) diff --git a/plugins/kbagent/commands/setup.md b/plugins/kbagent/commands/setup.md new file mode 100644 index 00000000..3603b0f0 --- /dev/null +++ b/plugins/kbagent/commands/setup.md @@ -0,0 +1,223 @@ +--- +description: One-command kbagent setup -- install the CLI if missing, connect a Keboola project (browser login, then an account login from the environment, then a static token), then verify with `kbagent doctor`. Idempotent; safe to re-run. +allowed-tools: Bash +argument-hint: [stack URL and/or a project alias, e.g. "https://connection.north-europe.azure.keboola.com" -- whatever is missing is asked for] +--- + +# /kbagent:setup -- get from zero to a verified connection + +Run the whole first-time setup in one invocation: CLI present, project +connected, setup verified. Every step is **conditional on a check**, so +re-running this after a partial setup only fills the gaps. + +## Non-negotiable rules + +- **Never print, echo, log, or persist a credential.** No secret in a + command line -- not `--token `, not `--password`, not + `--totp-secret`, not `echo`, not a heredoc. The CLI has hidden prompts + and reads `KBC_TOKEN` / `KBC_LOGIN_*` from the environment; use those. + Never *solicit* a password or TOTP seed either -- if those are not + already in the environment, that route is simply closed. +- **Use `--json`** for every check you have to parse. Parse the JSON; + do not scrape human-mode Rich output. One exception to know about: in + `--json` mode the auth commands print their human panel -- including a + device-login URL and code -- to **stderr**, and it is not in the JSON. If + you ever run one of those yourself, capture `2>&1`. +- **Do not re-run a step that already passes.** Never re-register or + overwrite an existing project or alias. +- **When a step needs a human, say so and stop guessing.** Browser login + (3a) and the hidden token prompt (3c) are human actions you hand over + rather than attempt: announce the command, then wait for the outcome. If + any login call you did run gets interrupted, check `kbagent --json auth + status` before re-running anything -- a blind retry is what orphans a + session. + +## Behavior + +1. **Is the CLI installed?** + ```bash + kbagent --json version 2>&1 + ``` + - **Runs** -> continue to step 2. If `kbagent.install_channel` is + present, this is a standalone/packaged build (Homebrew, Chocolatey, + winget, an unpacked archive, ...). **Respect it** -- do not run the + installer over it; the JSON's `upgrade_command` / `upgrade_hint` is + the only sanctioned way that install gets updated. + - **Not found** -> install it, but **check the platform first**: the + one-liner and its PATH fix-up are both POSIX-only. + + *macOS / Linux / WSL / Git Bash:* + ```bash + curl -LsSf https://raw.githubusercontent.com/keboola/cli/main/install.sh | sh + ``` + The installer puts `kbagent` on `PATH` for **its own process only**. + If `kbagent --json version` still fails right after, run + `source $HOME/.local/bin/env` (or tell the user to open a new shell) + and retry once. + + *Windows with no POSIX shell:* there is no `install.sh` route here and + `$HOME/.local/bin/env` does not exist. Quote the user the PowerShell + block from README's Install section + () -- `winget install --id + astral-sh.uv -e`, then `uv tool install` of the release wheel, then + `uv tool update-shell` -- and tell them `update-shell` edits the + *persisted* PATH, so they must open a **new** shell before `kbagent` + resolves. If Git for Windows is installed, README's documented + alternative is to run the POSIX one-liner through its bash instead. + Quote README rather than paraphrasing it; that block is versioned and + this file is not. + + Either way, if it fails a second time, stop and report the installer + output -- do not attempt a third install. + +2. **Is a project already connected?** + ```bash + kbagent --json project list + ``` + If the list is non-empty, say which aliases are already connected and + **skip straight to step 4**. Do not touch existing entries. + +3. **Connect a project.** This step needs the **stack URL**, and it needs it + first: login is not stack discovery, and step 2 just established there is + no registered project to infer one from -- so `auth login` without + `--stack` fails with `CONFIG_ERROR` ("No stack to log into"). Take the URL + from `$ARGUMENTS` when it looks like one; otherwise ask the user for it + before running anything (it is the host they see in the Keboola UI, e.g. + `https://connection.north-europe.azure.keboola.com`). + + Then work down this ladder and **stop at the first rung that lands**. It + is the order this repo has documented since 0.84.0 + (`plugins/kbagent/.claude-plugin/CLAUDE.md`, + `skills/kbagent/references/auth-workflow.md`): browser login -> account + login from the environment -> static token. + + **3a. Browser login -- the default, and nothing to paste. Hand this one + to the user; do not run it yourself.** + ```bash + kbagent auth login --stack --register-projects + ``` + This is the single step in this file that is **not** yours to execute. + `auth login`'s own docstring says an AI agent must not attempt it + headlessly, and the mechanics agree: PKCE waits `AUTH_CALLBACK_TIMEOUT` + (115 s) on the loopback callback, and the device-code fallback polls until + the server's `expires_in` -- minutes. A tool-run shell on a ~120 s + timeout gets **killed mid-flow**, and the kill tells you nothing: the + login may well have landed a second later. Re-running it blind is exactly + how you produce the `orphaned_session_id` warning, leaving a session + `kbagent auth logout` then has to chase. + + So print the command, say that it opens a browser (or prints a device + code) and that finishing it is theirs, and wait to be told it is done. + Note it is deliberately **without `--json`**: a human reading their own + terminal wants the panel, and in `--json` mode the verification URL and + code are written to **stderr**, not into the JSON payload. + + Then confirm it landed -- this part *is* yours: + ```bash + kbagent --json auth status + ``` + + `auth status` deliberately does **not** carry + `session_unsupported_features` (the surfaces a browser session cannot + serve). The login command prints them in the user's own terminal; to read + the list yourself, `kbagent --json auth register-projects --all` ships it + and is a no-op on anything already registered (status `exists`). Either + way relay it verbatim and never hand-list it from memory -- the canonical + copy is `SESSION_UNSUPPORTED_FEATURES` in + `src/keboola_agent_cli/services/_auth_registration.py`. + + **If 3a is not the answer, route on *why*** -- the two reasons are not + interchangeable, and treating them as one strands the user: + - **No browser at all** (headless host, container, CI, SSH without port + forwarding) -> try **3b**, then 3c. + - **The user needs one of the surfaces named in + `session_unsupported_features`** -> go **straight to 3c, skipping 3b**. + `login-password` mints the *same kind of session* as 3a -- both return + through `_finalize_login`, so both carry the identical + `SESSION_UNSUPPORTED_FEATURES` list -- so 3b would report success and + stop the ladder while leaving the user exactly as unable to do the + thing they came for. Only a static token serves those surfaces. + + **3b. Account login from the environment** (kbagent 0.84.0+) -- the + no-browser rung, and the only route into it. Try this *before* reaching + for a static token, whenever `KBC_LOGIN_EMAIL` and + `KBC_LOGIN_PASSWORD` are both already exported (plus + `KBC_LOGIN_TOTP_SECRET` if the account has TOTP-based MFA): + ```bash + kbagent --json auth login-password --stack --register-projects + ``` + The command reads all three values straight off the environment + (`commands/auth.py`, `envvar=` on `--email` / `--password` / + `--totp-secret`), so no secret enters the conversation and none lands on a + command line. Never pass them as flags. Two guards: + - **Version gate.** `login-password` does not exist before 0.84.0. + Compare `kbagent.version` from step 1; if it is older, skip to 3c. + - **`AUTH_MFA_INVALID`.** The account's MFA is WebAuthn/passkey-only, + which this grant cannot resolve without a browser -- and the only way + to reach 3b is that no browser is available. Go to 3c; do not retry + `login-password`, and do not loop back to 3a. + + If those variables are absent, skip 3b silently. Never ask the user to + export a password or a TOTP seed to satisfy this step -- a static token is + the smaller blast radius, which is exactly why it is the next rung. + + **3c. Static token -- the last resort.** + ```bash + kbagent --json project add --project '' --url + ``` + Never pass `--token` on the command line. Two safe routes: + - `KBC_TOKEN` is already exported in the environment -> run it as-is. + - Otherwise hand the command to the **user** to run in their own + terminal: `project add` prompts for the token with hidden input, and + that prompt needs a real TTY, which a tool-run shell does not have. + + Ask the user for the alias if `$ARGUMENTS` did not supply one. + +4. **Verify.** + ```bash + kbagent --json doctor + ``` + Read the check list off the JSON and interpret it for the user rather + than dumping it. Call out: + - config file + permissions and per-project connectivity -- any `fail` + here means step 2/3 did not really land; fix that before declaring + success. + - the **`claude_plugin` check** -- `pass` means the plugin is cached; + relay whatever note doctor attaches to it verbatim (a version-drift + hint naming the exact copy to update, or a migration hint if the + copy was installed from the deprecated marketplace). `warn` means + Claude Code is present but the plugin is not cached, so print the + `/plugin` lines doctor gives you. `skip` means Claude Code was not + detected on this host. Always quote doctor's own `/plugin` lines + rather than any names hardcoded here -- doctor is the single source + of truth for the marketplace and plugin names. `doctor` deliberately + does not install the plugin -- `/plugin` is an in-session user + command. + +5. **Close it out.** One short line: what is connected, and two or three + things to try next -- e.g. `/keboola list all configs in `, + `kbagent project list`, `kbagent context`. + +## Examples + +``` +/kbagent:setup +/kbagent:setup https://connection.north-europe.azure.keboola.com +/kbagent:setup my-prod-project +``` + +## Why this is a slash command and not a CLI subcommand + +- The last mile of setup lives *inside* Claude Code: `/plugin marketplace + add` and `/plugin install` are in-session commands a background CLI + cannot invoke (`services/doctor_service.py` says so explicitly). A + command that already runs in the session can at least read the plugin + state and speak plainly about it. +- Every step it runs is an existing, tested verb (`version`, `project + list`, `auth login`, `auth login-password`, `project add`, `doctor`). + This file is the + *ordering and the conditionals*, not new behavior -- so it cannot drift + away from the CLI's semantics. +- Idempotence is a checking discipline, and checks are cheap here: the + agent reads `--json`, compares, and skips. A shell script would have to + reimplement that. diff --git a/plugins/kbagent/skills/kbagent/SKILL.md b/plugins/kbagent/skills/kbagent/SKILL.md index 9a2f91b4..d650fb85 100644 --- a/plugins/kbagent/skills/kbagent/SKILL.md +++ b/plugins/kbagent/skills/kbagent/SKILL.md @@ -428,10 +428,23 @@ For detailed response parsing rules and common pitfalls, see [gotchas](reference ## First-time setup +**In Claude Code with this plugin installed, run `/kbagent:setup`.** It is +the one-command path: it installs the CLI if missing, connects a project +(browser login via `auth login --register-projects`, then +`auth login-password` from the environment, then a static token), +and verifies with `kbagent doctor`. Every step is conditional, so it is safe +to re-run on a half-finished setup. Run `/kbagent:setup` to see the steps it +takes -- it announces each one. + +Everything below is the manual equivalent -- for a plain shell, or another +agent, or when you want to drive the steps yourself. + If kbagent is not yet installed: ```bash -uv tool install git+https://github.com/keboola/cli +curl -LsSf https://raw.githubusercontent.com/keboola/cli/main/install.sh | sh +# the installer puts kbagent on PATH for its own process only -- +# 'source $HOME/.local/bin/env' or open a new shell kbagent doctor ``` diff --git a/src/keboola_agent_cli/commands/context.py b/src/keboola_agent_cli/commands/context.py index 651aca7f..c1502af1 100644 --- a/src/keboola_agent_cli/commands/context.py +++ b/src/keboola_agent_cli/commands/context.py @@ -2105,6 +2105,13 @@ /plugin marketplace add keboola/ai-kit /plugin install kbagent@keboola-claude-kit + /kbagent:setup + +`/kbagent:setup` is the one-command first-run path: it installs this CLI if +it is missing, connects a project (`auth login --register-projects`, falling +back to `auth login-password` from the environment and then a `project add` +static token), and verifies with `kbagent doctor`. +Every step is conditional, so it is safe to re-run. The plugin provides a skill with detailed workflow references including: - SQL transformation migration (input mapping removal, Snowflake paths)