> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elementum.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Elementum Development Kit (EDK)

> Get started with the Elementum Development Kit by installing the toolchain and SDK, authenticating, and pulling your organization.

<Warning>
  **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.
</Warning>

The Elementum Development Kit (EDK) is a code-first toolkit for representing Apps, Elements, Automations, Agents, Skills, Flows, Search Tables, and Approval Chains as TypeScript. Instead of clicking through the Elementum UI, you author changes as typed source, review a structural diff, and apply the approved changes to your organization.

<Info>
  The EDK is intended for engineers who prefer to build in code. If you're looking for the no-code path, start with the [Build an App](/getting-started/build-an-app) guide.
</Info>

## How the EDK Workflow Works

The EDK follows a Terraform-like lifecycle:

1. **Import or pull** the current state of your organization.
2. **Author changes locally** using typed catalog references.
3. **Plan** the changes and review the structural diff.
4. **Apply** the approved changes.
5. **Re-plan** to verify convergence.

This page covers the setup that makes those steps possible. Authoring is covered in [EDK Authoring](/edk/authoring), and planning and applying are covered in [Plan and Apply](/edk/plan-and-apply).

## Before You Begin

Make sure you have the following in place:

* **macOS.** The toolchain installer targets macOS — it installs the `elementum` binary to `~/.elementum/bin` and adds it to your `PATH` via `~/.zprofile`.
* **Node.js 24 or newer** installed locally.
* **Familiarity with TypeScript.** EDK projects are TypeScript, and the toolchain runs a project-level typecheck as part of `plan`.
* **A code editor or IDE** with a coding agent. Any environment that supports Node.js and TypeScript works.
* **An active Elementum account** with permission to create apps in your organization.
* **A terminal** where you can run `curl`, `npm`, and `elementum` commands.

<Info>
  The toolchain currently supports macOS only. Windows support is planned for a future release.
</Info>

<Tip>
  Confirm your Node.js version by running `node --version`. If it prints anything below `v24`, install a newer Node.js release before continuing.
</Tip>

<Note>
  Everything you author lives locally until you explicitly run `elementum apply`. You can keep the workspace under source control (Git, GitHub) without affecting your Elementum organization.
</Note>

## Set Up Your Project

<Tip>
  If you're new to the terminal, you don't have to run these commands yourself. Open a coding agent in your editor's command line, paste in the installation steps below, and let the agent run them for you.
</Tip>

<Steps>
  <Step title="Install the CLI Toolchain">
    Install the `elementum` toolchain with the distribution script:

    ```bash theme={null}
    curl -fsSL https://elementum-toolchain-distribution.vercel.app | sh
    ```

    The binary lands in `~/.elementum/bin` and is added to your `PATH` via `~/.zprofile`. Your current shell won't pick it up until the profile reloads.

    <Note>
      If you get `command not found` when you run `elementum`, open a new terminal or reload the profile in your current one:

      ```bash theme={null}
      source ~/.zprofile
      ```
    </Note>

    Verify the install:

    ```bash theme={null}
    elementum --version
    ```
  </Step>

  <Step title="Create a Workspace and Install the SDK">
    Create a workspace folder, initialize a Node.js package, and install the EDK SDK as a project dependency:

    ```bash theme={null}
    mkdir elementum-workspace && cd elementum-workspace
    npm init -y
    npm install @elementumai/edk
    ```

    The SDK is published to the public npm registry, so no auth token or `.npmrc` is required.

    <Tip>
      As the install runs, the new packages appear in your editor's file tree (for example, under `node_modules`), so you can watch the SDK land in your workspace.
    </Tip>
  </Step>

  <Step title="Install TypeScript">
    Install TypeScript as a dev dependency. The EDK SDK is validated against TypeScript `^6`:

    ```bash theme={null}
    npm install --save-dev typescript@^6
    ```

    A project-level `tsconfig.json` is required for `npx tsc --noEmit` to give useful output during authoring. The toolchain also runs its own entity-specific TypeScript checks as part of `plan`.
  </Step>

  <Step title="Install the Authoring Skill">
    The EDK packages an authoring skill that teaches AI coding assistants how to build EDK projects correctly. Install it with the toolchain-managed installer:

    ```bash theme={null}
    elementum skills install --yes
    elementum skills status
    ```

    During installation, the toolchain prompts you to select the AI coding agent you use, confirm, and install the skill into your workspace. `skills status` then confirms that the installed skill version matches the installed toolchain.

    <Warning>
      Use the toolchain installer above rather than adding the skill by hand. It initializes the supported local agent directories and enforces the skill/toolchain version match.
    </Warning>

    <Tip>
      Confirm the install worked by opening your code editor's agent panel and typing `/`. You should see an **Elementum EDK Authoring** entry in the slash-command list. Selecting it loads the prompts the agent uses when building EDK projects.
    </Tip>
  </Step>
</Steps>

## Authenticate to Your Organization

The toolchain authenticates against a specific Elementum instance, organization, and environment, and stores the result as a named profile. Sign in interactively with:

```bash theme={null}
elementum auth login --profile <profile>
```

`auth login` walks you through a series of prompts and stores the authentication profile locally under the name you pass to `--profile`. Press **Enter** to advance after each prompt:

1. **Instance** — select the Elementum instance (environment) that hosts your organization.
2. **Organization** — enter your organization name. This is the first segment of your Elementum URL. For example, if you sign in at `https://elementum.elementum.io/work`, your organization is `elementum`.
3. **Client ID and Client Secret** — paste the OAuth credentials you generate below.
4. **Environment** — choose the environment you'll author against. As a best practice, author against the lowest environment available (for example, a Dev or Test environment) and promote changes to higher environments from within Elementum after testing.
5. **Store the client secret** — choose **Yes** to save the credentials locally and finish signing in.

### Create OAuth Credentials

`auth login` asks for a Client ID and Client Secret from an OAuth token you generate in the Elementum platform:

1. Open your user profile from the bottom-right corner of the platform.
2. Select **OAuth** in the left navigation.
3. Click **Create New Token** in the top-right corner.
4. Enter a **Name** and an **Expiration** period, then enable these access levels:
   * **API Access**
   * **Read Only Access**
   * **Agents Execute Access**
5. Click **Generate Token**.
6. Copy the **Client ID** and **Client Secret** into the matching prompts in your terminal.

<Warning>
  The Client Secret is shown only once, at the moment you create the token. If you lose it, you'll need to generate a new token.
</Warning>

### Confirm You're Signed In

After signing in, confirm the active target for your profile:

```bash theme={null}
elementum --profile=<profile> auth status
```

`auth status` shows the instance, organization, and environment tied to the profile — always run it before `plan` or `apply` so you know which target you're about to change.

### Non-Interactive Environments

CI and other non-interactive environments can provide credentials through environment variables instead of `auth login`:

```bash theme={null}
ELEMENTUM_INSTANCE=us
ELEMENTUM_ORGANIZATION=blueprint
ELEMENTUM_ENVIRONMENT=production
```

<Warning>
  Do not commit client secrets or access tokens to your repository. Store them in your secret manager and inject them at runtime.
</Warning>

## Pull Your Organization

From your workspace directory, pull your organization to bootstrap the workspace:

```bash theme={null}
elementum --profile=<profile> pull org --data-only
```

This command:

* Creates the organization workspace when necessary, at a path like `<instance>/<organization>/`.
* Imports organization-level reference data, including CloudLinks and AI provider connectors.
* Creates generated catalog and state support files.
* Configures the workspace so the `@catalog` TypeScript alias resolves correctly.

<Note>
  `pull org --data-only` does **not** pull every App and Element as editable source. Apps and Elements are pulled individually — see [Pull existing entities](/edk/authoring#pull-existing-entities) in the Authoring guide.
</Note>

The first pull may take longer than subsequent runs because it performs remote discovery and initializes generated files. Times in the tens of seconds are common on the first run, and larger organizations continue to load over time.

Once it completes, an organization folder appears in your editor's file tree. Open the generated `<instance>/<organization>/generated/catalog.ts` file to see the Elements, CloudLinks, and connectors available in your organization.

## Enter the Workspace and Converge

`pull org` creates the organization workspace at `<instance>/<organization>/`. Move into it and run `init` to converge the workspace with your organization:

```bash theme={null}
cd <instance>/<organization>
elementum --profile=<profile> init
```

Once `init` finishes, the workspace mirrors your organization and you're ready to author changes. Before you deploy anything, preview the structural diff with `elementum plan` — see [Plan and Apply](/edk/plan-and-apply#debug-blocked-plans) if a plan reports unexpected differences at this stage.

## Build with a Coding Agent

The recommended way to work with the EDK is to direct a coding agent from your code editor or CLI. Once the [authoring skill](#set-up-your-project) is installed, the agent understands the EDK's conventions — how to authenticate, structure the workspace, use builders and the typed `@catalog`, and plan and apply changes — so you describe the outcome you want in plain language and let the agent produce the source.

<Info>
  Agent-driven authoring works in any code editor or CLI with a coding agent, as long as your EDK repo and the authoring skill are set up.
</Info>

### Let an Agent Handle Setup

You don't have to run the setup commands above by hand. In a new workspace, you can give a coding agent the setup steps — install the toolchain, create the workspace and install the SDK, install the authoring skill, authenticate, and pull your organization — and have it run them for you. This is useful if you're less comfortable in the terminal, or you just want to get to authoring faster.

<Tip>
  Even when an agent runs setup for you, review the results before authoring: confirm `elementum auth status` shows the intended target and that `pull org` created your organization workspace.
</Tip>

### Direct the Agent

When you delegate work to the agent, a few habits keep the results predictable:

* **Describe the business outcome and name the target.** Tell the agent what you're trying to accomplish and which App and Element it should work in. Ask it to confirm those are set up first — especially the Element that stores the underlying data.
* **Review the agent's approach before it writes code.** If your agent has a plan mode, use it so the agent outlines what it will change — and loads the authoring skill — before editing anything. This planning step belongs to the agent and is separate from the EDK's own `elementum plan` command, which previews the structural diff before you deploy.
* **Answer its clarifying questions.** The agent will ask scoping questions — how the change should behave, which tools it should include, how to handle seed data, and whether to modify the App. Your answers steer the design.
* **Give it the context it needs.** Point the agent at the models available in your organization and the supporting entities the change depends on. You can pull additional Apps and Elements into the same workspace so the agent has everything it needs to build a complete process.
* **Run agents in parallel when work is independent.** Because each change is just source in your workspace, separate agents can build unrelated parts of a process at the same time.

Some coding agents can apply edits automatically. Enable that only once you trust the plan the agent has proposed. For the full authoring context checklist, see [Work with the Authoring Agent](/edk/authoring#work-with-the-authoring-agent).

### Prompting Tips

Specific prompts produce better results than open-ended ones. When you write a prompt:

* **State the outcome, not the implementation.** Describe the business result you want and let the agent choose the entities and fields.
* **Name the workspace and target** so the agent edits the right App or Element — for example, `dev/my-org/apps/appRef`.
* **Include your guardrails in the prompt** — ask it to use plan mode, preserve existing `refName`s, reference other entities through `@catalog`, and hold off on `apply` until you've reviewed the plan.

The prompts below are generic starting points. Paste one into your agent and replace the bracketed placeholders with your own details.

Build a new capability in an existing App:

```text theme={null}
Using the Elementum EDK authoring skill, help me build out [App name] in the
[workspace path, e.g. dev/my-org/apps/appRef] workspace. I want to [describe the
business outcome]. First, confirm the App and the Element that stores [the relevant
data] are set up. Use plan mode and show me your plan before writing any code.
Preserve existing refNames and use @catalog for all references.
```

Add an automation to an existing App:

```text theme={null}
Using the Elementum EDK authoring skill, add an automation to [App name] in
[workspace path]. When [trigger condition], it should [action]. Create the
automation as DRAFT. Use plan mode and show me the plan first, and don't run
apply until I approve it.
```

Set up a new EDK workspace:

```text theme={null}
Set up an Elementum EDK workspace in this folder: install the elementum toolchain,
create the workspace and install @elementumai/edk and TypeScript, install the EDK
authoring skill, then walk me through elementum auth login and run
elementum pull org --data-only. Explain each step as you go.
```

Review and deploy changes you've already authored:

```text theme={null}
Run elementum plan on [workspace path] and summarize the diff for me. Do not run
apply. After I confirm, apply the same target and then re-run plan to verify it
converged.
```

### Review, Plan, and Apply

When the agent finishes, review the generated source, then run `elementum plan` to preview the structural diff and `elementum apply` to deploy — see [Plan and Apply](/edk/plan-and-apply). You can delegate these steps to the agent as well, but always review the plan output before anything is applied.

## Next Steps

<CardGroup cols={2}>
  <Card title="EDK Authoring" icon="pen-to-square" href="/edk/authoring">
    Pull entities, use builders and the typed `@catalog`, and work with the authoring agent.
  </Card>

  <Card title="Plan and Apply" icon="rocket" href="/edk/plan-and-apply">
    Preview the structural diff, deploy in stages when new fields are cross-referenced, and verify convergence.
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/edk/cli-reference">
    Every `elementum` command grouped by prefix, with usage and flags.
  </Card>

  <Card title="Build an App (No-Code)" icon="grid-2" href="/getting-started/build-an-app">
    Compare the EDK approach with building the same app through the Elementum UI.
  </Card>
</CardGroup>