Alpaco CLI is an open source developer command line tool for building and maintaining email design systems locally. It allows developers to pull templates into plain Liquid and JSON files, develop in VS Code or Cursor with live previews, run schema validations, and submit changes as safe review proposals.

Can an alpaco push break live production templates

No. A push never touches the live production template. Every push creates a pending change that generates a secure review link in the Alpaco web platform. A team administrator must inspect and publish the updates before they affect active campaigns. There is no force push command.

How JWT authentication works across multiple organizations

Alpaco CLI authenticates with a personal JWT token found in your account profile. That single token grants seamless access across all organizations, brand workspaces, and client accounts you belong to, eliminating credential juggling when managing multiple clients or brands from your terminal.

What file formats are used for local editing

The CLI uses standard human-readable files. Markup and logic live in clean Liquid files, while modular input configurations and schemas live in JSON. There are no binary blobs, obscure compile artifacts, or proprietary lock-ins. You can commit everything directly to your existing Git repository.

How pre flight validation protects marketer copy

When marketers build campaigns in Alpaco, their copy and images map to schema input keys. If an engineer renames or deletes an input key in config JSON, alpaco validate flags the conflict immediately. This prevents accidental regressions where existing campaigns lose content upon template updates.

Can Alpaco CLI run in GitHub Actions and CI pipelines

Yes. You can supply your ALPACO_TOKEN as an environment variable in GitHub Actions, GitLab CI, or any CI runner. Run alpaco validate on pull requests to enforce syntax correctness and schema integrity automatically before changes are merged or proposed.

What happens if a teammate edits the template online simultaneously

Alpaco tracks version locks. If someone updates the template in Alpaco while you are hacking locally, alpaco status warns you that your local files are outdated. You can run alpaco diff to review differences, pull the upstream changes, and re-apply your updates without overwriting colleagues' work.

CLI

Your Templates in Your Editor
Built for Speed and Accessibility

Pull any Alpaco template into plain Liquid and JSON files with one command. Build modules with local speed in VS Code or Cursor, and access your entire design system directly from your terminal.

$ npm install -g @alpaco-email/cli

Alpaco CLI on GitHub

~/templates/nordic-summer · alpaco-cli

bash

$ alpaco login
✓ Authenticated with platform.alpaco.email (token saved to ~/.config/alpaco/credentials.json)

$ alpaco pull tmpl_948f2a
✓ Pulled Nordic Summer (v14) into ./nordic-summer/

$ alpaco validate
✓ Schema verified: 6 blocks, 14 input groups, unique keys intact
✓ Liquid syntax valid: 0 errors across base/code.liquid & blocks/

$ alpaco diff
~ blocks/hero/code.liquid (+4 -2 lines)
+ blocks/curated-spotlight/ (new block added to template.json)

$ alpaco push
✓ Pushed as pending change #104
→ Review in Alpaco: https://platform.alpaco.email/t/nordic-summer/changes/104
ℹ Live template remains untouched until published by a team lead.

The 4-Step Dev Loop

CLI

# 1. Discover and pull
$ alpaco list
ID NAME LIVE PENDING
nordic-sum Nordic Summer v14 —
$ alpaco pull nordic-sum

# 2. Hack in your editor
$ code ./nordic-summer
Edit code.liquid, update config.json, commit to git

# 3. Check before proposing
$ alpaco validate && alpaco diff
✓ Everything passes

# 4. Propose for review
$ alpaco push
✓ Generated pending change #104

LOCAL DEVELOPER LOOP

Pull and Hack in Your Editor Then Push Safely

Keep your dotfiles, your keybindings, your Git branches, and your favorite IDE. The CLI explodes any Alpaco email template into plain files you can edit with standard tools, test with zero latency, and commit to version control.

Zero Proprietary Lock In

Pure Liquid templates, standard JSON schema, and universal file structures. No binary blobs, no opaque bundles, and no vendor lock-in.

Work in VS Code Cursor or Neovim

Use your preferred language servers, snippet collections, and AI coding assistants directly in your local environment.

Local Line by Line Diffs

Run alpaco diff anytime to inspect exact modifications against the live template before you propose your changes for review.

FILE ARCHITECTURE

Clean Diffable Files and Zero Magic

A template is simply an open directory. The directory is your single source of truth. Marketers configure inputs in the visual canvas, while you declare the code and schemas right next to the markup they control.

Diffable block ordering

To reorder blocks, simply reorder strings in the "blocks" array in template.json. Add a folder to add a block. Reordering is 100% diffable in git.

Companion Configuration Inputs

Each block includes a companion config.json where you define the typed inputs (text, image, color, toggle) that marketers safely edit without touching HTML.

Byte Identical Round Trips

An alpaco pull followed by an unedited alpaco push produces byte-identical JSON. The serializer is property-tested against production design systems.

Directory Anatomy Git Ready

acme-summer/

├── alpaco.json # template ID & pinned pulled version

├── template.json # design settings & block display sequence

├── vars/

│ └── global.json # global variables & design tokens

├── base/

│ ├── config.json # outer container input groups

│ └── code.liquid # email layout wrapper & responsive shell

└── blocks/

├── hero/

│ ├── config.json # marketer inputs: headline, CTA URL, image

│ └── code.liquid # modular Liquid component markup

├── curated-spotlight/

└── footer/

Guarded Review Pipeline ZERO LIVE OVERWRITES

Developer runs `alpaco push`

Generates an isolated pending proposal with an attributed changelog ID.

Pending Change #104 in Alpaco

Awaiting Review

Visual side-by-side diff testable by marketers. Live template is unchanged.

Published in Alpaco Web UI

Approved changes become the new live template version for marketers.

Single Profile JWT Token

All Orgs & Brands

SECURITY AND ACCESS

A Push Never Touches Live Campaigns Ever

Traditional developer tools risk breaking in-flight campaigns if a command pushes directly to production. Alpaco decouples template changes: pushing creates a pending change that must be reviewed and published in the web app. Paired with single-token JWT authentication, you gain seamless access across all organizations with zero live risk.

Push Means Proposing for Review

Every alpaco push creates an isolated pending change and outputs a direct review link where brand leads verify formatting before publishing.

Single Profile JWT for All Organizations

Authenticate once with the personal JWT token on your profile page. That single token grants you secure access to all templates across every organization, client account, and workspace without credential juggling.

Outdated branch detection

If someone alters the template in Alpaco after you pulled, alpaco status flags your local work as outdated to prevent silent overwrites.

No force push command

There is deliberately no --force push or live publish command in the CLI. Template releases are always governed through the Alpaco web platform.

PRE-FLIGHT VALIDATION

Catch Breaking Changes Before They Reach Marketers

Marketers store active campaign copy and images under your template's input keys. Renaming or removing a key accidentally would wipe out their content on the next layout update. Alpaco CLI applies strict template rules before every push.

Key Removal and Rename Warnings

The CLI flags if a block or input key has been removed or modified since the pull, preventing silent content loss in marketers' active drafts.

Liquid syntax parsing

Every code.liquid file is parsed against Liquid syntax standards, catching missing end tags, malformed variables, and logic errors.

Continuous Integration Test Automation

Run alpaco validate inside GitHub Actions using ALPACO_TOKEN to automatically reject invalid pull requests before merging.

Breaking Change Safeguard

validate

$ alpaco validate

[VALIDATION WARNING] blocks/hero/config.json:
⚠ Input key "hero_headline" was removed or renamed.

Existing campaigns store marketers' copy under this key.
Removing it will cause data loss next time someone clicks
"Update layout" in Alpaco.

Push aborted. To proceed intentionally with key deprecation, pass:
$ alpaco push --yes

COMMAND CHEAT SHEET

Everything You Need in Your Terminal

Simple, memorable verbs that match standard developer instincts. No complex flags or arcane configurations.

alpaco login

Authenticate with your profile JWT token to access templates across all organizations

alpaco pull

Download any template into local Liquid code and JSON files

alpaco validate

Verify syntax, block uniqueness, and guard against broken marketer keys

alpaco diff

Inspect line-by-line modifications against the live template before proposing

alpaco push

Submit changes as a safe pending proposal and get an instant review URL

Your Templates in Your Editor Built for Speed and Accessibility