Skip to main content

Documentation index: llms.txt. This page is also available as markdown: append .md to this URL or send Accept: text/markdown.

Local Development Setup Guide

Preview

This feature is currently available in a private preview and may not be accessible to all customers.

This guide sets up a workstation for local, AI-enabled Coalesce development: your pipeline as files in a Git repository, the coa CLI to build and run it, Coalesce Desktop to review it, and platform skills so your agent knows how to work with Coalesce. Click Copy for LLM at the top of this page, paste it into your AI agent, and ask it to walk you through the setup and run the steps that can be automated.

Coalesce DesktopDownload for macOS
Download for Windows
Coalesce platform skillscoalesce-platform-skills
Coalesce Domainhttps://app.coalescesoftware.io or your region or custom domain

Before You Begin​

You need three things. Each links to setup instructions if you don't have it yet. This guide won't cover them beyond that.

  1. An empty Git repository you can push to over HTTPS, on GitHub, Azure DevOps, GitLab, or your Git host. Step 3 covers creating one.
  2. Snowflake credentials: username, key pair (preferred) or password, plus a role, a warehouse, and the development database and schema you'll read from and write to. Never point local development at production or shared schemas.
  3. A Coalesce account on your organization's domain. If your organization is new to Coalesce, start with Set Up Your Project.
Joining an Existing Workspace?

If your team already builds this workspace in Coalesce, the repository, Project, and workspace files already exist. Your path is shorter:

  1. Install Coalesce Desktop (Step 1) and get your token (Step 2).
  2. Clone your workspace repository.
  3. Run coa init inside the clone. It detects the existing files and only sets up your credentials and your personal workspace.yml.
  4. If your storage locations use names other than SRC and TARGET, edit workspace.yml to match the names in locations.yml.
  5. Jump to Verify.

Step 1: Install Coalesce Desktop​

Download Coalesce Desktop for macOS, open the disk image, and drag Coalesce Desktop to Applications, then launch it.

Desktop bundles everything the rest of this guide needs, including Node.js and the coa CLI, so there is nothing else to install. Confirm the CLI is on your path:

coa --version

See Coalesce Desktop for what the app does, and Command Line Interface for the full CLI documentation.

Step 2: Get Your Coalesce Token​

Sign in to the Coalesce App and copy your refresh token, the same credential the REST API and Transform MCP use. See Get Your Token for the exact steps.

Treat the token like a password: paste it only where a tool asks for it (the CLI stores it in ~/.coa/config on macOS, %USERPROFILE%\.coa\config on Windows), and never commit it to Git.

Step 3: Create Your Workspace Repository​

Your workspace lives in a Git repository with an empty remote.

Creating a new repository. On GitHub, with the GitHub CLI (gh):

mkdir my-coalesce-workspace && cd my-coalesce-workspace
git init -b main
gh repo create my-coalesce-workspace --private --source .

On another Git host, or without gh: create the repository in your host's UI (leave "Initialize this repository with a README" unchecked), then:

git init -b main
git remote add origin <YOUR_REPO_URL>

Using an existing empty repository. Clone it and work inside the clone:

git clone <YOUR_REPO_URL>
cd <repository-name>

The remote must be empty. If your first push is rejected because the remote has commits, the repository was created with a README. Create a fresh empty one instead.

Step 4: Initialize the Workspace​

coa init

coa init runs interactively. It prompts for your Coalesce domain, your token, and your Snowflake connection details, live-tests the Snowflake connection before saving anything, and scaffolds the workspace files: data.yml, locations.yml, workspace.yml, and a .gitignore.

Snowflake OAuth

The CLI supports Snowflake key pair and username/password authentication. Snowflake OAuth is not yet supported for local development. If your organization requires OAuth, contact Coalesce support before starting.

The storage location prompts define where your pipeline reads and writes: the SRC and TARGET location names go to locations.yml, and your personal database and schema for each go to workspace.yml. You can edit both files later. See Storage Locations and Storage Mappings for the concepts.

If the connection test fails, nothing is written. Fix the credentials and rerun. Common causes: a key file missing its BEGIN/END lines, an unquoted passphrase with special characters, or a public key not yet assigned to your Snowflake user.

For Agents

coa init --non-interactive accepts a flag for every prompt, so an agent can run setup without stopping for input. Run coa init --help for the full flag list, and never echo tokens, passwords, or key contents while doing so.

Step 5: Create the Project in the Coalesce App​

Your workspace needs a cloud Project so deploys and collaborators can find it. In the Coalesce App:

  1. Go to Projects and create a new Project.
  2. Connect your Git account and attach the repository from Step 3 as the Project's repository. Set Up Version Control walks through this for each Git provider.
  3. Confirm the Project shows your repository URL in its settings.

This is the one setup step that happens in the browser. Keep the Project open in a tab; you'll use it again when you deploy.

Step 6: Commit and Push the Scaffold​

git add data.yml locations.yml .gitignore
git commit -m "Initialize Coalesce workspace"
git push -u origin main

workspace.yml and anything under .coa/ are personal configuration and stay out of Git. Confirm git status doesn't list them.

Step 7: Verify​

coa doctor
coa validate

Both should pass green: doctor checks config, authentication, and warehouse access; validate checks the workspace structure.

Equip Your Agent​

The workspace is ready. These two additions aren't required to build, but do both before you hand real work to your agent: they're the difference between an agent that can run coa and an agent that's good at Coalesce.

Install the Coalesce Platform Skills​

The platform skills teach your agent how to author nodes, structure pipelines, and use coa correctly.

Clone coalesce-platform-skills and copy the skills into your agent's skills directory for this workspace: for Claude Code, that is .claude/skills/ inside the workspace. The repository README covers other agents.

Connect Transform MCP​

The MCP gives your agent read and administrative access that complements the CLI build commands: run history, job status, and deployed Environments. Follow Connect to Transform MCP; it uses the same token from Step 2.

Smoke Test With Your Agent​

Open your workspace folder in Coalesce Desktop, then ask your agent to do a small piece of real work. For example:

Add a source node for <a table in your SRC schema> and run it.

You should see the node appear in Desktop as the agent creates it. When the run succeeds, your setup is complete.

What's in Your Workspace​

After setup your repository contains data.yml (platform and defaults), locations.yml (storage locations), and a nodes/ folder that fills up as you build, alongside folders for environments, jobs, and subgraphs as you add them. See What Gets Committed for the full layout.

Troubleshooting​

  • coa doctor or API calls return 401: your token was revoked or mistyped. Repeat Step 2 and rerun coa init.
  • coa doctor reports a missing workspace.yml: run coa doctor --fix.
  • First push rejected: the remote isn't empty. See Step 3.
  • Snowflake connection fails during init: see Step 4; init aborts before writing anything, so just rerun.
  • coa describe documents the commands and options of the CLI version you have installed. Trust it over any copied snippet, including this guide.

What's Next?​