Introduction

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 script CI runs
• 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>
 
...

Bare kst (no subcommand) prints the banner followed by --help, just like bare cargo or uv. Kasetto is CLI-only — every action has a dedicated subcommand. Pipe stdout or pass --color never to strip styling.

Creating a Config

Run kst init to generate a starter config:

kst init

Use kst init --global to create $XDG_CONFIG_HOME/kasetto/kasetto.yaml (or ~/.config/kasetto/kasetto.yaml).

Or let Kasetto edit the config for you — kst add <source> appends a source (preserving your comments) and syncs it in, and kst remove <source> reverses it, the cargo/uv way:

kst add https://github.com/org/skill-pack                       # add every skill
kst add https://github.com/org/skill-pack@v1.2.0                # `@<ref>` shorthand (cargo/uv-style)
kst add https://github.com/org/skill-pack --skill code-reviewer # or just named ones
kst add https://github.com/org/skill-pack --dry-run             # preview the edit, don't write
kst remove https://github.com/org/skill-pack --skill code-reviewer  # reverses the add

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

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).

You can also inherit from another config with extends:. A child config can pull in everything from a team base and override or extend it — see Extending Another Config.

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
    mcps: "*"

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

Print a table of installed assets:

kst list                    # all kinds together
kst list --type skills      # filter to one kind
kst list --json             # for scripting

With no --project or --global, global and project installs are shown together (each row labeled by scope).

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.