Repository navigation
12 AI Agents
AI agents and CI scripts can drive Flowline through its exit codes and error messages, which name the corrective action. There's also an agent plugin for Claude Code and Codex.
Install the plugin so Claude Code or Codex knows how to drive Flowline:
# Claude Code
/plugin marketplace add RemyDuijkeren/Flowline
/plugin install flowline@flowline
# Codex
codex plugin marketplace add RemyDuijkeren/Flowline
codex plugin add flowline@flowlineIt ships five skills, and the agent loads the relevant one on its own.
-
flowline: the core loop,push --dry-run→push→pull→deploy, and branching on exit codes. -
flowline-plugins: plugin steps and Custom APIs, class naming and attributes. See Push Plugins and Custom APIs. -
flowline-webresources: web resource naming, form event handlers and// flowline:annotations. See Push WebResources. -
flowline-generate: early-bound types and the generators. See Generate Early-Bound Types. -
flowline-migration: detects a spkl, Daxif, PACX, or ALM Accelerator project and walks through the matching guide (spkl, Daxif, ALM Accelerator, PACX), then checks the result withpush --dry-runandpull.
Exit codes are stable across versions.
Codes 3, 4, and 130 follow de facto CLI conventions (curl, git, rsync). Codes 10 to 21 are Flowline-specific.
| Code | Name | Meaning | Corrective action |
|---|---|---|---|
| 0 | Success | Command completed | None |
| 1 | GeneralError | Unexpected/unhandled error | Check error output |
| 3 | NotFound | Solution not in Dataverse or repo | Verify solution name matches .flowline
|
| 4 | NotAuthenticated | No PAC auth profile | Run: pac auth create --environment <url>
|
| 10 | ConnectionFailed | Dataverse environment unreachable | Check environment URL in .flowline
|
| 11 | ConfigInvalid |
.flowline or a settings file is missing or malformed, or a role keyword was used with no project to resolve it from |
Verify the named file exists and is valid. For a role keyword outside a project, pass the environment URL instead |
| 12 | DirtyWorkingDirectory | Uncommitted git changes block the operation |
git commit or git stash first |
| 13 | BuildFailed |
dotnet build or PAC pack failed |
Fix errors in Plugins/ and retry |
| 14 | VersionConflict | Reserved: allocated in the exit-code contract but never thrown today | None; this code doesn't currently occur |
| 15 | ValidationFailed | Drift detected, missing dependencies, invalid --force value, schema mismatch, flags that contradict each other, a target that is neither a role nor a URL, a role whose .flowline value isn't a URL, an environment whose type doesn't fit its role (such as deploy prod aimed at a sandbox), a scripted settings toggle/set write with no component name, or a managed deploy target still holding a staged upgrade |
Run flowline pull first; check error output. A staged upgrade prints the pac commands that clear it. An invalid --force value lists the ones that are valid for that command, and a flag conflict names both flags |
| 16 | Timeout | A Dataverse request got no response, or the PAC CLI 60-minute limit was exceeded | Re-run the same command. The write may already have landed, and the reconciling commands converge on a re-run; check environment health if it repeats |
| 17 | ForceRequired | Destructive or overwriting operation requires explicit confirmation: a declined confirmation (e.g. deploy's first-import prompt), provision refusing to overwrite an existing target, or a .flowline config overwrite declined non-interactively |
Add the --force <specifier> the message names, e.g. --force first-import, --force overwrite, --force config, --force recreate-assembly
|
| 18 | PartialSuccess | The run finished but part of it failed: deploy's orphan cleanup couldn't remove some components, settings apply couldn't write some of them, or a settings capture sweep couldn't reach an environment |
One failure and every failure share this code; read the printed counts. Fix what the output names, then re-run — both commands are safe to repeat |
| 19 | Inconclusive | A check couldn't run to completion: drift's empty-input guard skipped the comparison, a deploy verification step couldn't finish (e.g. a locked directory or a Dataverse query fault), or every component a settings apply file declared was absent from the target |
Not a pass/fail signal. Investigate the printed reason before trusting the result. For settings apply it usually means the wrong settings file or the wrong environment |
| 20 | WriteTargetOccupied | A file already occupies a path the command would write to: scaffold meeting an existing template file, or --output pointing at a file rather than a folder |
Distinct from 11: nothing is missing or malformed, something valid is in the way. Move the named file aside, or run the command somewhere else |
| 21 | AssemblyNotRegistered | Deploy completed but a plug-in package holds an assembly with no registration in the target, or one registered with no plugin types | Create the pluginassembly record under that package (sandbox isolation, matching version/culture/public key token), then deploy again so the content write populates its plugin types. This repeats every deploy until that record exists |
| 22 | ChangesFound |
diff --exit-code or drift --exit-code found changes between the two compared points |
Not a failure: the comparison ran and something differs. Only returned when --exit-code is passed, so a run without it reports changes and still exits 0 |
| 130 | Cancelled | Ctrl+C / SIGINT, the only way to reach this code. A second Ctrl+C quits without waiting for the run to unwind | Re-run if needed |
Codes 2 and 5 are intentionally unused.
Every error message says what happened and what to do next. These include the fix verbatim:
| Code | Message includes |
|---|---|
| 4 (NotAuthenticated) | run: pac auth create --environment <url> |
| 12 (DirtyWorkingDirectory) | Commit or stash changes first |
| 17 (ForceRequired) |
Use --force <specifier> to proceed, and the specifier named is always valid for the command that raised it |
| Command | What it does | When to run | What changes after |
|---|---|---|---|
clone |
Initialize project from an existing Dataverse solution | One-time setup per solution that already exists | Folder structure, unpacked XML, Plugins and WebResources projects, AGENTS.md, CLAUDE.md, DATAVERSE_CONTEXT.md
|
init |
Create publisher + empty unmanaged solution in DEV, then scaffold | One-time setup when the solution does not exist in Dataverse yet | Publisher and solution created in DEV; then everything clone produces; DEV URL saved to .flowline
|
push |
Register plugins and web resources to DEV | After plugin or web resource changes | DEV reflects current source; no pack/import involved |
pull |
Export from DEV, bump version, unpack to XML | After testing changes in DEV |
Solution/src/ updated; build version bumped; DATAVERSE_CONTEXT.md regenerated |
deploy |
Pack and import into target environment | After pull + commit |
Target environment updated with current solution version |
provision |
Create environment by copying from PROD | One-time setup for new environments | Environment URL saved to .flowline
|
generate |
Generate early-bound C# types from solution | After adding or modifying entities or custom APIs |
Plugins/Models/ overwritten with generated .cs files |
settings apply <target> |
Apply a settings file: environment variable values, connection reference bindings, component state | After deploy
|
Only the components the file names change; re-running the same file changes nothing. --dry-run writes nothing |
settings capture <target> |
Write a settings file from an environment | To create the file, or refresh it | Name the environment: omitting it exits 15 in a non-interactive run, and only prompts for which to capture at a terminal. Merges rather than overwrites. Secrets are never read; a placeholder is written instead |
settings toggle <target> [name] |
Turn one component on or off, or read its state | To toggle a component without a redeploy or a file edit | Give --on or --off to write, neither to read. --type flow|workflow|rule|bpf|action|plugin narrows it. Omit the name of a write in a non-interactive run and it exits 15, printing your command with <name> to fill in. Omit it on a read and it lists the components and exits 0, one per line as <glyph> <state> <type> <name> (● on, ◐ suspended, ○ off), ordered suspended then off then on. Forms and views are left out unless --type form or --type view is given; a full name still resolves them |
settings set <target> [name] |
Set one value or binding, or read it | To change one value without a redeploy or a file edit | Give --value to write, omit it to read. --type envvar|connref narrows it. An empty value is refused. Omit the name of a write in a non-interactive run and it exits 15, printing your command with <name> and <value> to fill in. Omit it on a read and it lists the names, without their values, and exits 0 |
drift |
Report what deploy's orphan cleanup would delete |
Before deploy, or as a standalone check on prod/test
|
Read-only, nothing changes |
diff |
Report which solution components changed between two points in git history | Before a commit, or between two tags to read what a release contains | Read-only, nothing changes unless --write is passed |
scaffold |
Write a project template (webresources) into the current folder |
Adding web resources to a repo that has none |
WebResources/ project written where you are standing, and added to the nearest solution file (searched upward to the .flowline/.git root) when there is one. --output moves the folder, --name names it. No Dataverse call |
status |
Show environment, auth, and git state | Before running commands; when troubleshooting | Read-only, nothing changes |
sln add |
Add a .cdsproj to the solution file |
A repo assembled by hand or migrated off another tool | Solution file updated, found by searching upward to the .flowline/.git root, same rule as scaffold. No Dataverse call |
dotnet build # build plugin assembly
flowline push # register DLL + web resources in DEV
flowline push --dry-run # preview changes before touching Dataverse
# make changes in the maker portal if needed
flowline pull # pull solution state from DEV, unpack to repo
git add . && git commit -m "..." # commit the unpacked XML diff
flowline deploy test # promote to TEST
flowline deploy prod # promote to PROD- Use Flowline, not
pac solutiondirectly. -
Pick
initvscloneby whether the solution already exists in Dataverse.initcreates one and refuses a unique name that's already taken;cloneadopts an existing one. -
initruns against Sandbox and Developer environments only. Anything else is refused with exit15. -
initnever prompts in a non-interactive run. Pass<solution-name>,--env <url>, and--publisher-prefix <prefix>. Each missing one fails naming the flag. -
-e/--env <role|url>targetsclone,init,push,pull, andgenerate.init,push, andpullaccept DEV only: thedevkeyword, the saved DEV URL, or a URL Flowline reads as DEV (not Production, and not named-test/-uat); passing anything else fails naming that.generateaccepts any role;cloneaccepts any role too, since it's usually reading from PROD. A URL not yet in.flowlinegets saved under the role Flowline infers from it, or the one you pick interactively. -
pullrequires a clean working directory. Exits12if there are uncommitted changes inSolution/src/. Commit or stash first. -
deploypacks from source, not from a previous export. Local changes not yet synced to DEV exit15. Runpullfirst. -
--force <specifier>is required for destructive operations in non-interactive mode.--forcealways takes a value naming the exact hazard being approved (e.g.--force dirty,--force config,--force overwrite). Without it, Flowline exits17. See 04-Command-Reference for the per-command--forcevocabulary. -
statusis read-only. Use it to check connectivity and auth. -
Unknown flags fail strictly. An option Flowline doesn't recognize, including an old or removed spelling, fails with
Error: Unknown option '<name>'.and exit15.
.flowline ← environment URLs + solution config
docs/DATAVERSE_CONTEXT.md ← schema snapshot for AI agents (auto-generated)
Solution/<SolutionName>.cdsproj ← solution metadata
Solution/src/ ← unpacked solution XML (git-diffable)
Plugins/<SolutionName>.Plugins.csproj ← plugin source, decorated with [Step] attributes
WebResources/<SolutionName>.WebResources.csproj ← web resource build project
WebResources/dist/ ← web resource files synced to Dataverse by push
AGENTS.md ← scaffolded by flowline clone / init (this file)
CLAUDE.md ← scaffolded by flowline clone / init (`@AGENTS.md` import)
Need a genuine second solution in one repo? Two documented patterns: a separate repo per solution (default), or a nested solutions/<Name>/ folder inside one repo containing multiple independent, self-contained Flowline projects (each with its own .flowline, Solution/, Plugins/, WebResources/).
flowline clone writes an AGENTS.md file at the repo root with the solution name substituted throughout. It includes:
- The daily dev loop for this specific solution
- Project structure with actual paths
- Exit code reference table
- Rules for this project
An existing AGENTS.md is never overwritten.
GitHub Copilot and Codex load AGENTS.md automatically on project open. Claude Code does not read AGENTS.md directly, it only auto-loads CLAUDE.md, so flowline clone also scaffolds a one-line CLAUDE.md containing @AGENTS.md, which Claude Code resolves as an import. Same skip-if-exists behavior applies. Keep AGENTS.md accurate as the project evolves.
After every successful flowline clone or flowline pull, Flowline writes docs/DATAVERSE_CONTEXT.md, a curated markdown snapshot of the solution schema optimised for AI token efficiency.
| Section | Content |
|---|---|
| Solution | Display name, unique name, version, publisher prefix |
| Entities | Logical name, display name, EntitySetName, ownership type |
| Attributes | Logical name, type, required level, description, custom flag |
| Option sets | Inline value → label mapping for picklist and boolean fields |
| Forms | Condensed tab → section → field list (hidden controls excluded) |
| Views | Column list and filter summary (no verbatim FetchXML) |
| Workflows | Display name, activation state, trigger entity |
| Plugin steps | Message, entity, stage (pre/post-operation), mode (sync/async), class name |
| Connection references | Display name, connector ID |
Sections with no content are omitted. No GUIDs appear in the output.
flowline clone seeds AGENTS.md with a "Dataverse schema context" section at the end:
## Dataverse schema context
- [ContosoSales](docs/DATAVERSE_CONTEXT.md)
@docs/DATAVERSE_CONTEXT.mdThe @ import causes Codex and GitHub Copilot to load the schema automatically on every request from AGENTS.md, and Claude Code to load it via the CLAUDE.md → AGENTS.md import chain.
Every flowline pull adds the import and link back if they're missing. Without an AGENTS.md, pull warns; run flowline clone to scaffold it.