Installing & Using the CLI

Installing & Using the CLI

The dm CLI (the @datamagik/cli npm package) is the command line for building custom SPA apps: scaffold a project, log in, declare resources, generate types, run a dev server with hot reload, and publish versions. Every command has rich help — run dm --help or dm <cmd> --help.

Requirements

• Node.js (18+ recommended) and npm.
• A DataMagik account with the Builder permission.
• An API key (dcp_ token) created in the platform UI under your profile's API Keys.

Install

The easiest path is to scaffold a starter, which installs the CLI for the project:

# Scaffold a starter (prompts for "simple" or "showcase")
npx @datamagik/cli init my-app
cd my-app && npm install

Or add it to an existing Vue project as a dev dependency (invoke it with npx dm), or install it globally to get a bare dm command:

npm install -D @datamagik/cli     # then: npx dm <cmd>
# or
npm install -g @datamagik/cli     # then: dm <cmd>

Log in

# Interactive — paste your dcp_ API key when prompted
dm login --url https://data-magik.com

# Non-interactive
dm login --url https://data-magik.com --token dcp_xxxxxxxx

Credentials are stored at ~/.config/datamagik/credentials.json (mode 0600). Use your staging host (for example https://staging.data-magik.com) for non-production work.

Configure the app — dm.config.json

Set appId to your application's id and declare the resources the app may use. This file is the source of truth for both autocomplete and runtime authorization — commit it.

{
  "appId": 123,
  "entry": "index.html",
  "sources": [
    { "sourceId": 17, "type": "lookup_table", "alias": "parts" },
    { "sourceId": 42, "type": "script",       "alias": "postReceipt" }
  ],
  "serialSeries": [{ "seriesId": 3, "alias": "lotSerial" }],
  "printers": [{ "printerId": 11, "alias": "line1Zebra" }]
}

Command reference

• dm init [name] — scaffold a new SPA project (simple or showcase starter).
• dm login --url <host> [--token dcp_...] — authenticate against a platform host.
• dm add [type] [id] [--alias name] — declare a resource (lookup table, ODBC query, script, serial series, printer). Interactive search if you omit arguments.
• dm typegen [--watch] — generate src/dm.generated.ts from your declared resources (commit it).
• dm dev [--context k=v ...] — run a Vite dev server with hot reload, proxied auth, and a simulated context.
• dm publish [--message "..."] — build, zip dist/, and upload a new live version.
• dm script / dm sql — author and run DataMagik scripts and SQL queries locally.

Typical workflow

npx @datamagik/cli init my-app && cd my-app && npm install
dm login --url https://data-magik.com
# set appId in dm.config.json
dm add lookup_table 17 --alias parts
dm typegen
dm dev --context order=42
dm publish --message "first version"

Prefer your editor? The VS Code extension wraps these same commands.