feat(cli): add checkly init command with skill-first onboarding

[thebiglabasky]

Summary

Adds npx checkly init — a new onboarding command that replaces npm create checkly@latest with a streamlined, AI-agent-aware flow. The skill installation is front and center: install the skill, get a tailored prompt copied to your clipboard, hand off to your agent.

• npm create checkly@latest now shows a deprecation notice pointing to npx checkly init
• npx checkly (no args) nudges toward init and skills install when no config is detected
• Starter prompts are stored as .md files in src/ai-context/onboarding-prompts/ — easy to review and tweak without touching TypeScript
• Clipboard integration uses native OS commands (pbcopy/xclip/xsel/clip) with silent fallback — no external dependency

Supported paths (all tested)

State	Skill?	Playwright?	Behavior
Pristine	Installs	No	Deps → base prompt → agent footer
Pristine	Installs	Yes	Deps → PW prompt → agent footer + pw-test/reporter hints
Pristine	Declines	No	Demo checks? → config → deps → manual footer
Pristine	Declines	Yes	Demo checks? → config → deps → PW hint → footer
Existing	Has skill	-	Refresh skill silently → concise next steps
Existing	Installs	-	Existing-project prompt → agent footer
Existing	Declines	-	Concise next steps
Agent mode	Auto	-	Clean JSON output, no prompts
CI mode	Skip	-	Config + deps silently

Reuses existing CLI utilities

• findPlaywrightConfigPath from services/util.ts (extended with .mts/.mjs)
• defaultFilenames from checkly-config-loader.ts
• detectPackageManager for robust PM detection (lockfiles, config, runtime, user agent)
• promptForPlatformTarget shared between skills install and init
• logSymbols via shared successMessage() helper
• PLATFORM_TARGETS — skill directories derived from it to prevent drift

Points of attention for reviewers

• Prompts copy needs marketing review — all user-facing text is in messages.ts (shared blocks) and onboarding-prompts/*.md (agent prompts). Easy to change in one place.
• Clipboard relies on OS commands — works on macOS/Linux (with xclip or xsel)/Windows. Falls back gracefully with a "copy the prompt below" message. No external npm dependency.
• Boilerplate templates in src/ai-context/onboarding-boilerplate/ are excluded from tsconfig (not compiled) and vitest (not test files) — they're copied to dist at build time.
• AI context references updated: AssertionBuilder method reference added, public URL requirement documented, plan-tier location restrictions noted, env var auth promoted as primary path, npm create checkly references updated to npx checkly init.

Test plan

• Run through the 9 interactive paths in the table above
• Test agent mode: CLAUDECODE=1 npx checkly init
• Test npx checkly with no config — should show nudge
• Test npm create checkly@latest — should show deprecation notice
• Run npx vitest run — 740+ tests pass
• Verify clipboard works (macOS at minimum)

🤖 Generated with Claude Code

[MichaelHogers]

LGTM

Looks quite alright, not a ton of time to look at details

[thebiglabasky]

critical to ensure we don't overwrite stuff during tests

[stefanjudis]

If I get the context correctly, this message isn't great. An "empty this" is never great and I'm unsure how npx checkly skills install helps directly. Shouldn't we be more explicit here?

[thebiglabasky]

I need to re-review in context, but believe it might be related to some content above and as I refactored for reuse of messaging that made things look disconnected. But that likely can be improved, I agree 👍🏻

[stefanjudis]

Could we have the copy logic in prepare-ai-context? I think it already copies stuff around. :) Would also keep the package.json cleaner.

[thebiglabasky]

I thought that was done already, as I had that remark before. Good catch, thanks!

[stefanjudis]

I've spent 30min reviewing the code. I'll play around with it to see how it feels and approve if everything feels great.

[stefanjudis]

Nit: should we decide on the line length in the print? I could see this fighting back for folks running in a heavily split view?

---

I'm not sure how I feel about these new "lines" and "line dividers"...

I also had trouble understanding what I was looking at. I "think" I'd appreciate a manual step with some explanations to make things very clear. People only read the last line so I wonder how many people don't see it on first try.

#pseudo code
Use the provided example prompt to set up Checkly.
Wanna copy prompt to clipboard (Y/n)?

Great. Paste it and see the magic.

---

This footer feels a bit like a deadend to me.

I'm not really sure what to do with it. Having at least a checkly.config created or something. This feels like "use AI or we leave you hanging".

---

When running the provided install command, I'm seeing this.

This is a bit odd because I've just run npx checkly init. 🤔

It also runs install again.

It's not a huge deal, but we might want to add a guard for this?

---

FYI It hallucinated this.

---

Confirmation Protocol

Write commands (e.g. incidents create, deploy, destroy) return exit code 2 with a confirmation_required JSON envelope instead of executing. Always present the changes to the user and wait for approval before running the confirmCommand. Never auto-append --force. This applies to every write command individually — updates and resolutions need confirmation too, not just the initial create.

I'm unsure if this is expected but it happily deployed and destroyed my checkly stuff when I told it to. I'm unsure if this is expected. In my demos with similar safety guardrails, Claude usually goes "Are you sure I should deploy now"?

---

I see that we're branching out depending on the question, if a person wants to use the AI skills? I found this a bit surprising. In my mind, the question of whether I want to use an agentic setup flow should be called out very explicitly.

# Pseudo code
Do you want your agent to set up your Checkly project? (Y/n) Y
Your agent will perform best with an installed Checkly skills. Install? (Y/n)

---

Alrighty. :) I think this is a great step forward! 👏 But right now I'm not very ready to approve bc after playing with it for an hour, I think we can polish some more things. But great work!

And yeah, before deprecating the old way of installing things, I'd really ship this "secretly" and let solutions play with it...

[thebiglabasky]

I also had trouble understanding what I was looking at. I "think" I'd appreciate a manual step with some explanations to make things very clear. People only read the last line so I wonder how many people don't see it on first try.

I now realized I was only seeing the inline comments.
Great remarks. I'll iterate on these later.
There is still no way we will keep two competing onboarding options though, otherwise there's no way we can attribute behavior to anything, and that's a pit I don't want to fall into.
That's even more push to get this pristine and great 🙌🏻

[github-actions]

🎉 Experimental release successfully published on npm

npm install checkly@0.0.0-pr.1267.217090c

[stefanjudis]

2nd round

✅ Going without AI

 ../../checkly/checkly-cli/packages/cli/bin/run init

  checkly v0.0.1-dev
  Monitoring as code, AI-native.

✔ Do you want your AI agent to set up Checkly? … no
✔ Created checkly.config.ts
✔ Added checkly and jiti to package.json
✔ Run npm install to install them now? … yes
✔ Installed dependencies
✔ Add some demo checks to get started? … yes
✔ Created __checks__/ with example checks

All done! Next steps:

  npx checkly login
  Log in or create a free account

  npx checkly test --record
  Dry run your checks and record results

  npx checkly deploy
  Deploy checks to Checkly

  You have a Playwright test suite — you can also:

  npx checkly pw-test
  Run Playwright tests on Checkly infrastructure

  Install the Checkly Playwright Reporter for
  trace uploads:
  https://checklyhq.com/docs/detect/testing/playwright-reporter/

  Docs:  https://checklyhq.com/docs/cli
  Slack: https://checklyhq.com/slack

---

This feels great!

Well done!

---

This is great too!

---

I think we should sneak something into the PCS configure skill (or wherever). I could totally see how questions like this could cause confusion.

Later on:

Yes, it doesn't understand that dependencies will be handled by Playwright in Checkly and tries to support that. We should def add some sentences.

---

We also need to document somewhere that playwrightConfig is only for browser checks and multistep checks. Right now Claude wants to set up PCS and is fiddling with the wrong property.

---

I assume the branch is outdated? 🤔

---

Alright. I've run through the process twice and I think it feels great.

@thebiglabasky Feel free to assign me a ticket with the PWT / PCS things I pointed out. Some sentences in the skills should probably do the trick. :)

[thebiglabasky]

Thanks!
Yes PWCS is the most finicky. Let's update the branch and tweak what needs to be: feel free to do it directly in it if you have time before I do (tonight on my end)
Thanks @stefanjudis !

[stefanjudis]

🚢