Skip to main content

Import & Export

SLAW exports squads to portable markdown packages and imports them from local directories or GitHub repositories. Use export to back up a squad, share it as a template, or version-control your agent team.

Prerequisites
  • SLAW installed and running (see Quickstart). The slaw CLI is on your PATH, or use npx slaw.
  • To export: an existing squad and its ID (pass --squad-id or set it in your CLI context).
  • To import into an existing squad: the target squad's ID.
  • To import from GitHub: network access to the repository (private repos need credentials configured for git).

Package format​

An exported squad follows the Agent Squads specification and uses this directory structure:

my-squad/
├── SQUAD.md              # Squad name, description, and metadata
├── agents/
│   ├── squad_lead/
│   │   └── AGENT.md      # Agent identity, role, and instructions
│   └── coder/
│       └── AGENT.md
├── projects/
│   └── main/PROJECT.md
├── skills/
│   └── review/SKILL.md
├── tasks/
│   └── onboarding/TASK.md
└── .slaw.yaml            # Adapter types, env inputs, and budget declarations

Never exported: secret values, machine-local paths, or database IDs.

Export a squad​

slaw squad export <SQUAD_ID> --out ./my-export

By default this exports the squad definition and its agents. Use --include to control exactly what is bundled:

# Export squad, agents, and projects
slaw squad export <SQUAD_ID> --out ./backup \
  --include squad,agents,projects

# Export everything — including tasks and skills
slaw squad export <SQUAD_ID> --out ./full-export \
  --include squad,agents,projects,tasks,skills

# Export specific skills only
slaw squad export <SQUAD_ID> --out ./skills-only \
  --include skills --skills review,deploy

Export options​

OptionDescriptionDefault
--out <path>Output directory (required)—
--include <values>Comma-separated: squad, agents, projects, issues, tasks, skillssquad,agents
--skills <values>Export only specific skill slugsall
--projects <values>Export only specific project shortnames or IDsall
--issues <values>Export specific issue identifiers or IDsnone
--expand-referenced-skillsVendor skill file contents instead of keeping upstream referencesfalse

Import a squad​

Import from a local folder, GitHub URL, or GitHub shorthand:

# From a local folder
slaw squad import ./my-export

# From a GitHub repository
slaw squad import https://github.com/org/repo

# From a GitHub subfolder
slaw squad import https://github.com/org/repo/tree/main/squads/acme

# Using GitHub shorthand
slaw squad import org/repo
slaw squad import org/repo/squads/acme

Preview before applying​

Always run --dry-run before a live import. The preview shows what will be created, renamed, skipped, or replaced — including any environment variables that will need values after the import:

slaw squad import org/repo --target existing \
  --squad-id <SQUAD_ID> --dry-run

Target modes​

ModeWhen to use
newCreates a fresh squad from the package. Good for applying a template.
existingMerges the package into an existing squad. Requires --squad-id.

If --target is not specified, SLAW infers it: when a --squad-id is provided (or one exists in context), it defaults to existing; otherwise new.

Collision strategies​

When importing into an existing squad, agent or project names may conflict with existing ones:

StrategyBehaviour
rename (default)Appends a suffix to avoid conflicts (e.g. squad_lead becomes squad_lead-2)
skipSkips entities that already exist
replaceOverwrites existing entities (not available via the Squad Lead API)

Pass --collision <strategy> to choose. When running interactively, SLAW shows a checkbox picker before applying so you can select exactly which agents, projects, skills, and tasks to import.

Pin a GitHub ref​

slaw squad import org/repo --ref v2.0.0 --dry-run

Non-interactive import (CI or scripts)​

slaw squad import ./package --target new --yes --json

Common workflows​

Clone a squad template from GitHub:

slaw squad import org/squad-templates/engineering-team \
  --target new \
  --new-squad-name "My Engineering Team"

Add agents from a package into your existing squad:

slaw squad import ./shared-agents \
  --target existing \
  --squad-id <SQUAD_ID> \
  --include agents \
  --collision rename

After import: re-enable agents​

Imported agents always land with scheduled heartbeats disabled. Assignment-based and on-demand wake behaviour is preserved, but scheduled runs stay off until you re-enable them in Routines & Schedules or the agent settings.

API endpoints​

The CLI commands use these endpoints under the hood:

ActionEndpoint
Export squadPOST /api/squads/{squadId}/export
Preview import (new squad)POST /api/squads/import/preview
Apply import (new squad)POST /api/squads/import
Preview import (existing squad)POST /api/squads/{squadId}/imports/preview
Apply import (existing squad)POST /api/squads/{squadId}/imports/apply

Squad Lead agents use the safe import routes (/imports/preview and /imports/apply), which enforce non-destructive rules: replace is rejected, and collisions resolve with rename or skip. Issues are always created as new.

Verification​

After an export, confirm the package was written:

ls ./my-export
# Expect: SQUAD.md, agents/, .slaw.yaml (plus projects/, skills/, tasks/ if included)

SQUAD.md should carry your squad's name and description, and each included agent should have an agents/<name>/AGENT.md. Secret values are never present in the output.

Before an import, the --dry-run preview lists exactly what will be created, renamed, skipped, or replaced, plus any environment variables that will need values. Confirm that list matches your intent before re-running without --dry-run.

After an import, the imported squad (or merged agents) appears in the dashboard sidebar. Remember that imported agents land with scheduled heartbeats disabled — re-enable them in Routines & Schedules before expecting scheduled runs.

Next steps​