First Steps with Kasetto

When you need this: You want a quick, predictable path to "working sync" and you're not sure what Kasetto will modify.

What you'll learn:

• How to create a config and run your first sync
• How to preview changes and avoid interactive UI
• Where to go next for the exact sync/merge guarantees

Once you've installed Kasetto, run kst to make sure it's available:

kst
A declarative AI agent environment manager

Usage: kst <COMMAND>

...

If there's no kasetto.yaml in the current directory, Kasetto greets you with an interactive home screen. Navigate with J / K or arrow keys, press Enter to run the selected command, or use shortcut keys:

Key	Action
I	Init
S	Sync (prompts for config path)
L	List
D	Doctor
C	Clean
U	Self update
Q / Esc	Quit

Set NO_TUI=1 if you'd rather skip the interactive screen and get plain text hints.

Creating a Config

Run kst init to generate a starter config:

kst init

Or create a kasetto.yaml by hand:

agent: claude-code

skills:
  - source: https://github.com/org/skill-pack
    branch: main
    skills:
      - code-reviewer
      - name: design-system

Tip

Use the agent field to target any of the supported agents, or use the destination field for a custom install path.

Syncing Skills

Run kst sync and Kasetto does the rest:

kst sync
Syncing skills from 1 source...
  ✓ code-reviewer (installed)
  ✓ design-system (installed)
Synced 2 skills in 1.2s

Kasetto pulls the skills and installs them into the right agent directory. Next time you run sync, only what changed gets updated.

If you want the "exact contract" for what gets copied/removed, read How Sync Works.

Syncing from a Remote Config

Got a shared team config? Just pass it as a URL:

kst sync --config https://example.com/team-skills.yaml

For private configs hosted on git providers, set the right env var token first (see Authentication).

Previewing Changes

Not ready to commit? Use --dry-run to see what would happen first:

kst sync --dry-run
Would install: code-reviewer, design-system
Would remove: old-skill

See CI & automation for recommended CI patterns.

MCP Servers

Kasetto can also manage MCP server configs. Add an mcps section to your config:

agent: claude-code

skills:
  - source: https://github.com/org/skill-pack
    skills: "*"

mcps:
  - source: https://github.com/org/mcp-pack

Kasetto merges them into each agent's native settings file during sync — nothing extra to do.

If you want the exact merge rules and conflict behavior, see How Sync Works.

Exploring What's Installed

Want to see what's installed? Open the browser:

kst list

Navigate with J / K, switch tabs with Tab or H / L, scroll with Page Up / Page Down, jump with G G / Shift+G. With no --project or --global, global and project installs are shown together (each row is labeled by scope). Use --plain, set NO_TUI=1, or pipe stdout for plain text instead of the full-screen browser.

Want to check your local setup:

kst doctor

Doctor shows your version, lock file location, install paths, last sync time, and any skills that failed.

Using JSON Output

sync, list, doctor, clean, and self update support --json for scripting or CI:

kst sync --json
kst list --json
kst doctor --json
kst clean --json

Next Steps

See the configuration reference for the full config schema, browse the commands reference, or grab a ready-to-use pattern from the cookbook.