feat(cli): improve tigris init and add npx tigris alias

[designcode]

Summary

Two changes to tigris init, plus the package that makes npx tigris init work.

init no longer offers to install a CLI you already have

The wizard advertised CLI - Global in its "Defaults" hint and ran a CLI step on every run, regardless of whether tigris was already on PATH. Now:

• The PATH check moved ahead of the mode prompt, so the hint reflects reality:

  	hint
  tigris on PATH	MCP - Global, Skills - Project
  not on PATH	CLI - Global, MCP - Global, Skills - Project

• An existing install is updated rather than reinstalled, by delegating to tigris update. That command runs its own registry check and getUpdateCommand() picks the path matching how the CLI was installed — npm install -g, brew upgrade tigris, or the curl/PowerShell installer for standalone binaries. Forcing npm install -g from init could fail or leave a second copy on PATH. It's a no-op when current, so nothing needs checking before calling it — which let the bespoke fetchLatestVersionCapped helper and its ref'd-timer handling go away entirely.

• If that update fails (offline, no write permission), it can leave a CLI predating init --agent in place. Handing such an agent tigris init --agent just errors, so the handoff degrades to npx. Detected by probing (--agent only writes to stdout, captured and discarded) rather than comparing against a hardcoded 3.5.0, so it stays correct as the recipe moves.

init --agent picks the CLI step instead of delegating the decision

The recipe used to print both branches and let the agent evaluate them:

1. If `tigris` isn't on $PATH (`command -v tigris`), ask permission, then `npm install -g ...`.
2. If `tigris` is on $PATH, ensure it's latest version using `tigris update`.
3. Check if the user is already authenticated ...

init already knows which applies, so it now emits one unambiguous step and renumbers the rest:

tigris on PATH:   1. Ensure the CLI is on the latest version: `tigris update`.
not on PATH:      1. Ask permission, then install the CLI: `npm install -g @tigrisdata/cli --ignore-scripts`.

New tigris package

An unscoped alias so the CLI is reachable without the scope:

npx tigris init

bin.js is one line — import '@tigrisdata/cli' — which runs the CLI in-process, so argv, stdio, signals and exit codes all pass through unchanged, and --version/help still report the real CLI (Commander takes its program name from specs.yaml, not the filename). Every command works, not just init.

.changeset/config.json gains "fixed": [["@tigrisdata/cli", "tigris"]] so the alias can never drift from the CLI it wraps.

Testing

• pnpm test — 811 pass, 214 skipped. Added test/lib/init/{plan,shared}.test.ts (10 tests); init had none before.
• pnpm lint, tsc --noEmit, and the binary tsconfig.binary.json typecheck all clean. publint clean on both packages.
• Both recipe branches exercised against the built CLI, with and without tigris on PATH.
• Confirmed empirically that init --agent shipped in 3.5.0: 3.4.3 and older exit 1 with unknown option '--agent', which is what the handoff probe keys on.
• Wrapper installed from a publish-shaped tarball against the registry CLI — both tigris and t3 bins work, including through npx.
• Dry-ran changeset version and reverted: both packages land on 3.7.0.

⚠️ Before this releases

npm trusted publishing must be configured for the tigris package name. The release workflow publishes via OIDC with no NODE_AUTH_TOKEN, and tigris currently exists on npm as a 0.0.0 placeholder that predates this repo. If the trusted publisher isn't set up, @tigrisdata/cli@3.7.0 will publish and tigris will fail — leaving npx tigris resolving to the placeholder, which the wizard's fallback handoff now points users at.

Follow-up (not in this PR)

init isn't in the generated CLI README at all — #203 added the command without running pnpm updatedocs. Regenerating produces a large unrelated diff, so I left it out; happy to do it separately.

🤖 Generated with Claude Code

---

Note

Medium Risk
Onboarding and global npm publish path change; mistaken PATH handling could mis-detect installs, and the new tigris package must publish correctly or npx handoffs break.

Overview
tigris init now treats an on-PATH CLI as already installed: the Defaults hint omits CLI - Global, existing installs are refreshed via tigris update (not forced npm install -g), and the agent handoff uses npx tigris init --agent when update fails or the CLI is too old for init --agent.

When run via npx/pnpm dlx, PATH is scrubbed of throwaway runner .bin dirs so init does not mistake the ephemeral binary for a real install.

tigris init --agent prints one resolved first step (install or update) via buildAgentSetup, instead of both PATH branches for the agent to interpret.

Adds the unscoped tigris package (re-exports @tigrisdata/cli) so npx tigris works; changesets fixed @tigrisdata/cli and tigris together. New tests cover the agent recipe and PATH helpers.

^{Reviewed by Cursor Bugbot for commit c49efff. Bugbot is set up for automated code reviews on this repo. Configure here.}

[greptile-apps]

Greptile Summary

This PR improves CLI detection and agent setup instructions while adding an unscoped tigris npm alias.

• Moves CLI detection ahead of interactive setup choices and delegates existing installations to tigris update.
• Generates an install-or-update agent recipe based on detected CLI availability.
• Adds the tigris wrapper package and fixes its release version to @tigrisdata/cli.
• Updates documentation, command examples, tests, and the workspace lockfile.

Confidence Score: 4/5

The PR should not merge until npx tigris init --agent correctly recognizes that its transient executable is not a persistent CLI installation.

The newly advertised npx path inherits a temporary tigris binary on PATH, causing the generated recipe to omit installation even though every later setup command requires tigris after the npx process exits.

Files Needing Attention: packages/cli/src/lib/init/index.ts and packages/cli/src/lib/init/shared.ts

Important Files Changed

Filename	Overview
packages/cli/src/lib/init/index.ts	Selects the agent recipe from PATH detection, but npx's transient executable is misclassified as a persistent installation.
packages/cli/src/lib/init/interactive.ts	Reworks install/update behavior and introduces capability-based fallback after failed updates.
packages/cli/src/lib/init/plan.ts	Refactors the static agent recipe into a generated, consecutively numbered install-or-update plan.
packages/cli/src/lib/init/shared.ts	Centralizes CLI detection and spawn options, though inherited PATH cannot distinguish npx from a global installation.
packages/tigris/package.json	Defines the public unscoped alias package with CLI bins and a workspace dependency on the scoped CLI.
packages/tigris/bin.js	Delegates execution in-process to the scoped CLI package.
.changeset/config.json	Keeps the alias and scoped CLI package versions fixed together.

_{Reviews (1): Last reviewed commit: "feat(cli): skip CLI install in init when..." | Re-trigger Greptile}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want higher recall? High effort reviews run extra passes and find more bugs. A team admin can switch effort levels in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 810ad19. Configure here.}