Skip to main content
Limited Release. The EDK is currently in limited release and is not available to all customers. Commands, generated file layouts, and package APIs may change before general availability. Confirm you’re on the latest EDK version before starting new projects.
Once you’ve authored changes in your EDK workspace, deploying them is a two-command loop: plan shows the structural diff between your source and the live environment, and apply executes it. This page covers both commands, the staged approach required when new fields are cross-referenced, and the design principles that keep deployments predictable.
This page assumes you have a working EDK workspace and pulled entities. If not, start with Getting Started and then EDK Authoring.

​
Plan Changes

plan compares your local source to the current state of the deployed environment and reports what would change. Always run plan before apply — even a clean TypeScript check doesn’t guarantee that every referenced platform handle exists in the target environment.

​
Target the Whole Workspace or a Single File

You can plan across the whole organization workspace:
Or narrow the target while iterating. Narrower targets run faster and produce smaller diffs:
Prefer the narrowest target that still covers your dependencies. A workspace-wide plan is only necessary when you want a full picture before a large release.

​
Plan Symbols

A plan report uses four symbols to describe each entity’s status: Always inspect the structural diff before applying. A blocked entry is information about dependencies, not a bug — see the debugging section below for how to interpret it.

​
Apply Changes

After reviewing the plan, apply the same target:
For safer iteration, apply the narrowest complete dependency set — for example, an owning Element’s file before its dependents:
apply mutates the live environment. Confirm the active target with elementum auth status before applying — especially in a shared environment where the wrong ELEMENTUM_ENVIRONMENT can push development changes into production.

​
Verify Convergence

After every apply, re-run plan against the same target:
The expected result is:
Anything else means the applied change didn’t fully converge — for example, a field was created but a dependent layout still needs a follow-up apply. This is the primary signal for the two-stage deployment pattern below.

​
Two-Stage Deployment

When a change introduces fields that are referenced by other new definitions in the same commit, a single apply cannot converge. New fields do not have platform field handles until the owning App or Element has been created or updated, so layouts, dynamic picklists, Automations, Agents, Skills, Search Tables, and dependent entities cannot resolve those handles before they exist. A reliable sequence:
  1. Add and apply the owning App or Element fields.
  2. Refresh the deployed bindings — for example, by re-running pull org or an additional pull.
  3. Add or restore layouts that reference the new fields.
  4. Apply the layouts.
  5. Plan and apply dependent Automations, Agents, Skills, and Search Tables.
  6. Plan the complete dependency set again and verify convergence.
You can author the final design first — layouts, dependent Automations, and all — but deployment may still need to be staged. A common pattern during a first apply is to temporarily omit layouts that reference newly added fields, apply the fields, then restore and apply the layouts.

​
Design Decisions

The following patterns keep EDK deployments safe, especially when multiple engineers share an organization.

​
Preserve Identity During Renames

Change visible names and descriptions freely, but do not change deployed UUIDs, handles, or stable refNames unless you intend an identity migration. A display rename is safe. A refName change typically replaces the entity in the target environment and can orphan existing records or relationships.

​
Separate Process Records from Authoritative Data

  • Apps should own workflow records and process-specific stages.
  • Elements should own reusable domain data that can be shared across processes.
Modeling process state on an Element (or authoritative data on an App) tends to force awkward cross-entity coupling later.

​
Deploy Dependencies in Order

Rather than deploying an entire cross-entity design at once, deploy in dependency order and verify each stage before moving to the next:
  1. Owning Apps and Elements
  2. New fields
  3. Layouts and cross-entity relationships
  4. Automations, Agents, Skills, and Search Tables
  5. Process orchestration

​
Apply to the Lowest Environment First

Point the EDK at your lowest environment — typically development — and use Elementum’s platform deployments to promote the resulting objects into higher environments. This keeps the EDK workflow focused on authoring against a single controlled target, and lets the platform handle environment-specific configuration when promoting between dev, test, and production. Before every apply, confirm the active target with elementum auth status so you never accidentally apply development changes to production.

​
Choose a Single Authoring Surface Per Project

Decide up front whether a given App or Element is authored from the EDK or from the Elementum platform, and keep the whole team on the same surface for that object. Mixed authoring — some team members editing in the EDK while others edit in the UI — creates conflicts in objects and automations: concurrent changes diverge, plan diffs repeatedly report unexpected updates when a UI edit lands between pulls, and it becomes unclear which surface is authoritative. If some team members need to work in the platform while others use the EDK, agree on a clear ownership model per object type (for example, EDK owns automation logic while the platform owns layout tweaks) and pull frequently to stay in sync.

​
Create New Objects in the Platform First

The EDK is designed for iterating on Apps and Elements that already exist. Create new objects in the Elementum platform first, then pull them into your workspace with elementum pull app --id <id> or elementum pull element --id <id>. This lets the platform assign namespaces, handles, and initial layout defaults, and gives the EDK a clean, deployed starting point for further authoring in TypeScript. See Pull existing entities for the details.

​
Debug Blocked Plans

A ! in the plan output usually means a new field is being referenced before its platform handle exists. Common triggers:
  • A layout references a field that hasn’t been applied yet.
  • An automation references an automation output that hasn’t been created yet.
  • A search table’s --aspect or --search-table UUID has not been generated on the platform.
The fix is almost always a staged field deployment, not a hard-coded UUID or an edit to a generated state file. Follow the two-stage deployment sequence above:
  1. Apply the field-only change first.
  2. Re-plan — the blocked entries should now resolve to + or ~.
  3. Apply the dependents.

​
Handle Transient Failures

If apply returns HTTP 0 or another transport failure mid-run, do not blindly retry the same apply. Instead:
  1. Run plan against the same target to see what actually converged.
  2. Trim your target to the entities that didn’t apply.
  3. Re-apply.
Blind retries after a transport failure can double-apply entities that already converged and produce misleading diffs.

​
Next Steps

CLI Reference

Every elementum command grouped by prefix, including plan, apply, auth, and pull.

EDK Authoring

Revisit builders, @catalog handle-tokens, and the authoring agent workflow.