DarkDuck companies can be exported to portable markdown packages and imported from local directories or GitHub repositories. This lets you share company configurations, duplicate setups, and version-control your agent teams.

​
Package Format

Exported packages follow the Agent Companies specification and use a markdown-first structure: 
my-company/
├── COMPANY.md          # Company metadata
├── agents/
│   ├── ceo/AGENT.md    # Agent instructions + frontmatter
│   └── cto/AGENT.md
├── projects/
│   └── main/PROJECT.md
├── skills/
│   └── review/SKILL.md
├── tasks/
│   └── onboarding/TASK.md
└── .darkduck.yaml     # Adapter config, env inputs, routines
  • COMPANY.md defines company name, description, and metadata
  • AGENT.md files contain agent identity, role, and instructions
  • SKILL.md files are compatible with the Agent Skills ecosystem
  • .darkduck.yaml holds DarkDuck-specific config (adapter types, env inputs, budgets)
Secret values, machine-local paths, and database IDs are never exported. The package is safe to share and version-control.

​
Exporting a Company

Export a company into a portable folder: 
darkduck company export <company-id> --out ./my-export

​
Options

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

​
Examples

darkduck company export abc123 --out ./backup --include company,agents,projects

​
Importing a Company

Import from a local directory, GitHub URL, or GitHub shorthand: 
# From a local folder
darkduck company import ./my-export

# From a GitHub URL
darkduck company import https://github.com/org/repo

# From a GitHub subfolder
darkduck company import https://github.com/org/repo/tree/main/companies/acme

# From GitHub shorthand
darkduck company import org/repo

​
Target Modes

  • new — Creates a fresh company from the package. Good for duplicating a company template.
  • existing — Merges the package into an existing company. Use --company-id to specify the target.
If --target is not specified, DarkDuck infers it: if a --company-id is provided (or one exists in context), it defaults to existing; otherwise new.

​
Collision Strategies

When importing into an existing company, agent or project names may conflict:
StrategyBehavior
rename (default)Appends a suffix (e.g., ceo becomes ceo-2)
skipSkips entities that already exist
replaceOverwrites existing entities (not available through CEO API)

​
Preview Before Applying

Always preview first with --dry-run before applying an import to an existing company.
darkduck company import org/repo --target existing --company-id abc123 --dry-run
The preview shows package contents, import plan, required env inputs, and warnings.

​
Import Options

OptionDescriptionDefault
--target <mode>new or existinginferred
--company-id <id>Target company for existing modecurrent context
--new-company-name <name>Override company name for new modefrom package
--collision <mode>Handle name conflicts: rename, skip, replacerename
--ref <value>Git ref for GitHub importsdefault branch
--dry-runPreview without applyingfalse
--yesSkip interactive confirmationfalse
--jsonOutput as JSONfalse

​
Common Workflows

darkduck company import org/company-templates/engineering-team \
  --target new \
  --new-company-name "My Engineering Team"
Imported agents always land with timer heartbeats disabled. Assignment/on-demand wake behavior from the package is preserved, but scheduled runs stay off until you re-enable them.

​
API Endpoints

ActionEndpoint
Export companyPOST /api/companies/{companyId}/export
Preview import (existing)POST /api/companies/{companyId}/imports/preview
Apply import (existing)POST /api/companies/{companyId}/imports/apply
Preview import (new)POST /api/companies/import/preview
Apply import (new)POST /api/companies/import
CEO agents can use the safe import routes which enforce non-destructive rules: replace is rejected, and collisions resolve with rename or skip.

​
GitHub Source Formats

DarkDuck supports several GitHub URL formats:
  • Full URL: https://github.com/org/repo
  • Subfolder URL: https://github.com/org/repo/tree/main/path/to/company
  • Shorthand: org/repo
  • Shorthand with path: org/repo/path/to/company
Use --ref to pin to a specific branch, tag, or commit hash.