CLI Reference
Complete reference for the squads command-line tool.
npm install -g @squads-sh/clisquads add <source>
Install a squad into your project from a GitHub repository or the marketplace. The squad is downloaded, validated, and placed in your project's squads directory.
squads add <github-user/repo> [options]--dir <path>Target directory for installation (default: ./squads)--branch <name>Git branch to install from (default: main)--forceOverwrite existing squad if already installedInstall from GitHub
squads add acme/design-system-squadInstall to a custom directory
squads add acme/api-squad --dir ./my-squadsInstall from a specific branch
squads add acme/dev-squad --branch developsquads find [query]
Search the marketplace for squads by keyword, category, or tag. Returns a list of matching squads with install counts and ratings.
squads find [query] [options]--limit <n>Maximum number of results (default: 20)--sort <field>Sort by: relevance, installs, rating, newest--category <name>Filter by categorySearch by keyword
squads find "design system"Search with sorting
squads find api --sort installsBrowse all squads (no query)
squads find --sort newest --limit 10squads list
List all squads installed in the current project. Shows name, version, agent count, and installation path.
squads list [options]--jsonOutput in JSON format--verboseShow detailed information for each squadList installed squads
squads listList in JSON format for scripting
squads list --jsonsquads check
Validate all installed squads. Checks for structural integrity, missing files, broken cross-references, and outdated versions.
squads check [options]--fixAttempt to auto-fix common issues--strictFail on warnings (not just errors)Run validation
squads checkValidate and auto-fix
squads check --fixsquads update [squad]
Update one or all installed squads to their latest version. Without a squad name, updates all squads.
squads update [squad-name] [options]--dry-runShow what would be updated without making changes--forceForce update even if local modifications existUpdate all squads
squads updateUpdate a specific squad
squads update design-system-squadPreview updates
squads update --dry-runsquads remove <squad>
Remove an installed squad from your project. Cleans up the squad directory and any synced slash commands.
squads remove <squad-name> [options]--keep-configPreserve configuration files after removal--forceSkip confirmation promptRemove a squad
squads remove old-squadRemove without confirmation
squads remove old-squad --forcesquads init [name]
Initialize a new squad project with scaffolding. Creates the directory structure, squad.yaml, and starter agent/task/workflow files.
squads init [name] [options]--template <name>Use a starter template (minimal, standard, full)--preset <name>Apply a domain preset (api, frontend, devops)Create a new squad
squads init my-squadUse a template
squads init my-squad --template standardInitialize in the current directory
squads initsquads publish [path]
Publish a squad to the marketplace. The squad is validated, a security audit is triggered, and it becomes discoverable by the community.
squads publish [path] [options]--access <level>Visibility: public or private (default: public)--tag <version>Publish with a specific version tag--dry-runValidate without actually publishingPublish the current directory
squads publishPublish a specific squad
squads publish ./squads/my-squadDry run to validate before publishing
squads publish --dry-runsquads login
Authenticate with squads.sh using your GitHub account. Required before publishing squads.
squads login [options]--token <token>Authenticate with an API token instead of OAuthLogin via GitHub OAuth
squads loginLogin with an API token
squads login --token sk_live_abc123