datocms

datocms login

datocms link

git init

npm install

datocms login

npm install --save-dev datocms        # if missing
npx datocms login                          # user, one-time, interactive
npx datocms projects:list [hint] --json    # agent discovers siteId
npx datocms link --site-id=<ID> [--organization-id=<ID>]   # agent links

datocms link

projects:list

which datocms

npx

• datocms

  in

  package.json

  devDependencies → CLI available

• datocms.config.json

  with a

  siteId

  on the active profile → linked

• npx datocms whoami

  succeeds → OAuth session active
• none of the above → drive the bootstrap above

.env

DATOCMS_API_TOKEN

npx datocms schema:inspect

--json

| jq

cma:call item_types list

fields list

../datocms-cli/references/schema-inspect.md

DATOCMS_CMA_TOKEN=...

.env

cma:call

cma:script

1. Read

   package.json

   and check for these packages (in priority order):

   • @datocms/cma-client

     — Universal/isomorphic package. Recommended for most cases. Works in any environment with native

     fetch

     . Only provide a

     fetchFn

     if your runtime lacks native Fetch API.

   • @datocms/cma-client-node

     — Node.js-optimized. Adds upload helpers (

     createFromLocalFile

     ,

     createFromUrl

     ). Use when you need file-system upload convenience methods.

   • @datocms/cma-client-browser

     — Browser-optimized. Adds

     createFromFileOrBlob()

     for File/Blob uploads.
2. If none is installed and the task requires

   buildClient()

   code, recommend the appropriate package:
   • General / universal →

     @datocms/cma-client

   • Node.js project needing upload helpers →

     @datocms/cma-client-node

   • Browser-only project needing File/Blob uploads →

     @datocms/cma-client-browser

   (For pure OAuth-path work via

   cma:call

   /

   cma:script

   , none of these need to be installed — the CLI workspace ships its own client.)
3. Search for existing

   buildClient()

   calls to understand how the project already configures the client (API token source, environment targeting, etc.).
4. Only if the deliverable is unattended runtime code (see Step 1a): check for a

   .env

   or

   .env.local

   file and see whether a CMA-enabled

   DATOCMS_API_TOKEN

   (or similar) is already defined. If the only variable present is something read-only (

   DATOCMS_READONLY_API_TOKEN

   ,

   NEXT_PUBLIC_DATOCMS_API_TOKEN

   , a CDA token), flag that a separate CMA-enabled token is needed for that specific runtime — not for the agent's own introspection, which must go through CLI + link regardless.
5. Check for an existing

   cma-types.ts

   file to determine if CMA type generation is already set up. Do not proactively suggest setting up type generation. For

   cma:docs

   lookups,

   cma:call

   , and

   cma:script

   this skill owns the execution shape directly — see the cheat sheets in Step 4. For schema-change requests, see the decision tree in Step 2.5 — it covers when this skill owns the work directly and when it routes to datocms-cli migrations. Otherwise route to datocms-cli for CLI-workflow topics (

   schema:generate

   , environment operations, imports, plugin management, multi-project sync, CI/CD).

can_access_cma: true

• Content operations — Create, read, update, delete, publish, or unpublish records
• Upload operations — Upload files, manage assets, update metadata, bulk tag
• Schema operations — Create or modify models, fields, fieldsets, block models
• Filtering & querying — Search records, filter by fields, paginate large collections
• Localization — Work with localized field values and multi-locale content
• Blocks & modular content — Modular content fields, single-block fields, nested block payloads
• Structured text & block tooling — DAST payloads, embedded blocks, block traversal, debugging helpers
• Environment operations — Fork, promote, rename, delete sandbox environments
• Webhook & deploy operations — Configure webhooks, build triggers, deploy management
• Access control — Create roles, manage API tokens, invite users
• Scheduling — Schedule publish/unpublish, manage workflows
• Migration & scripting — Bulk data operations, content seeding, field migrations
• Type generation — Consume generated CMA schema types or wire typed record operations
• Dashboard & schema menu management — Organize navigation sidebar items, group models in menus
• Plugin management — Install, configure, or audit plugins programmatically
• Project settings & usage — Site settings, maintenance mode, subscription limits, usage tracking, white-label
• Saved filters — Create or manage saved record/upload filter views
• Audit & debugging — Query audit logs, inspect async job results, CMA-side search

bulk_destroy

field_type

string → json

json → string

datocms-cli

migrations:new

required

datocms-cli

cma:call

cma:script

cma:script

migrations/

cma:call

cma:docs

cma:script

cma:call

cma:script

cma:script

datocms-cli

• User-requested one-offs, content operations, and the direct-mutation branch of a reversible schema change are this skill's core:

  cma:call

  ,

  cma:script

  stdin-mode, and

  cma:script

  file-mode. Stay here and load the references in Step 3.
• Destructive schema changes, the migration branch of a reversible schema change, and anything that must be committed/versioned/replayed across environments are better covered by datocms-cli (

  migrations:new

  ,

  migrations:run

  ). Switch when the change is destructive, when the repo already uses a migrations workflow, or when the user wants the change as a reviewable migration. The handoff is loading the sibling skill's references — do not bounce the user.
• Unattended runtime code (CI, app server, webhook, long-lived automation) is a separate scenario — that is where a checked-in

  buildClient()

  script belongs. See Step 4 ("Client Setup").

1. npx datocms cma:docs <resource> <action>

   is the live, always-up-to-date source for endpoint shapes, payload attributes, validators, and client TypeScript signatures. Always reflects the installed client version — never stale. Use it as the default for every "what does this endpoint accept / return" question.
2. The reference files in this directory carry opinionated mental models, decision trees, cross-cutting workflows, and pattern ordering invariants — things

   cma:docs

   doesn't know. Use them for the "how should I approach this" questions.

cma:docs

is a CLI command — its full surface (flags, naming convention, when to pass

--expand-types

) lives in the sibling skill. Load the datocms-cli skill and read

../datocms-cli/references/direct-cma-calls.md

§ cma:docs the first time this skill needs to consult endpoint documentation. That file is the single source of truth for the command; do not re-derive the flags from this skill.

buildBlockRecord<Schema.X>

client.items.create<Schema.X>

--types-depth 2

--expand-types <SpecificType>

--expand-types "*"

• references/client-setup-and-errors.md

  — Package choice, client setup, token/environment config, error handling

1. Run

   npx datocms cma:docs <resource> <action>

   to fetch the live endpoint shape, payload attributes, and TS signatures.
2. Then load the reference listed below for the workflow, mental model, ordering invariants, and gotchas

   cma:docs

   doesn't carry.

cma:docs <resource>

references/records.md

references/uploads.md

references/schema.md

references/filtering-and-pagination.md

references/localization.md

references/editing-records.md

references/editing-records.md

references/environments.md

references/access-control.md

references/migration-patterns.md

references/type-generation.md

references/project-settings-and-usage.md

references/resource-gotchas.md

references/resource-gotchas.md

references/resource-gotchas.md

references/resource-gotchas.md

references/resource-gotchas.md

references/resource-gotchas.md

• If the task involves localized fields in any context → also load

  references/localization.md

• If the task uses

  raw*()

  methods, generated CMA types, advanced client behavior, or platform limits → also load

  references/client-types-and-behaviors.md

• If the task involves modular content, single-block fields, DAST structured text, block traversal, or any per-locale backfill → also load

  references/editing-records.md

• If the task involves listing many records → also load

  references/filtering-and-pagination.md

• If the task is a migration script → also load

  references/migration-patterns.md

  plus whatever domain refs are needed
• If the task involves video upload subtitles/tracks or upload tag management → also load

  references/resource-gotchas.md

  § Upload tracks and tags
• If the task involves maintenance mode before a migration → also load

  references/project-settings-and-usage.md

• If the task involves checking subscription limits before bulk operations → also load

  references/project-settings-and-usage.md

• CLI + link is a prerequisite of Step 4, not a choice. If the project is not yet linked, fix that first (propose install + login + link) before writing any solution code.
• For interactive / one-off work (the majority of CMA tasks), do not write

  buildClient({ apiToken: ... })

  code at all — output a

  cma:call

  invocation (single call with shape from

  cma:docs

  ) or a

  cma:script

  invocation (stdin-mode for loops/multi-step, file-mode when a heredoc becomes painful) using the shapes below. The CLI handles auth silently via the linked project; no cross-skill hop needed.
• Only when the deliverable is unattended runtime code (CI, server-side app, long-lived automation, repo-committed shared scripts) should the response include

  buildClient()

  + env-var token code.

cma:script

Schema.*

client

Schema

tsc --noEmit

any

unknown

@datocms/cma-client-node

datocms-structured-text-*

parse5

export default

npx datocms cma:script <<'EOF'
const items = await client.items.list({ filter: { type: 'article' } });
console.log(items.length);
EOF

export default async function(client: Client)

.ts

tsconfig.json

tsc --noEmit

$

// tmp/scripts/publish-drafts.ts
import type { Client } from 'datocms/lib/cma-client-node';
// Optional typed project schema — run once next to the script:
//   npx datocms schema:generate ./datocms-schema.ts
// import * as Schema from './datocms-schema';

export default async function (client: Client): Promise<void> {
  for await (const draft of client.items.listPagedIterator({
    filter: { fields: { _status: { eq: 'draft' } } },
  })) {
    await client.items.publish(draft.id);
  }
}

npx datocms cma:script tmp/scripts/publish-drafts.ts [--environment <env>]

• Use

  cma:call

  first for a single call with a shape you can read from

  cma:docs

  . Reach for

  cma:script

  only when the task needs loops, pagination, branching, dependent calls, or typed

  Schema.*

  payloads.
• stdin-mode for quick hacks: pipes, heredocs, one-liners. No file on disk, no project prerequisites.
• file-mode when a heredoc hurts: long script, nested quoting, local helper imports, or you want to rerun the file by name. Requires

  datocms

  reachable in

  node_modules

  from the file's directory; place the file in a gitignored scratch dir (

  tmp/scripts/

  ,

  scratch/

  ,

  ~/scratch/dato/

  ). Prefer a migration for code you want to commit, version, and replay across environments, and do not put file-mode scripts under

  migrations/

  — that directory is owned by

  migrations:run

  .
• Typed

  Schema.*

  in file-mode is opt-in: run

  npx datocms schema:generate ./datocms-schema.ts

  next to the script and

  import * as Schema from './datocms-schema'

  . In stdin-mode

  Schema.*

  is ambient — no generation needed.
• Import path matters for promotion: file-mode imports

  Client

  from

  datocms/lib/cma-client-node

  — the same import migrations use, so a file-mode script can be promoted into a migration with a plain

  mv

  into

  migrations/

  (signature matches too).
• Redirect

  2>/dev/null

  when piping stdin-mode stdout into

  jq

  .
• Pre-installed packages are stdin-only. In file-mode, install what you need into your own

  package.json

  .
• Reach for a checked-in

  buildClient()

  script only when the code must run unattended (CI, app server, webhook, long-lived automation). See "Client Setup" below.

• Default to

  buildClient()

  from the detected package (Step 1b)
• Read the API token from an environment variable; never hardcode it and never ask the user to paste it into the chat
• Set the

  environment

  option when working with sandbox environments

• Default to the simplified API (e.g.,

  client.items.create()

  ) because it handles serialization/deserialization automatically
• Switch to

  raw*()

  methods only when the task explicitly needs raw JSON:API payloads, relationship metadata, or generated CMA schema types are intentionally part of the solution

• Prefer

  *.listPagedIterator()

  (for example

  client.items.listPagedIterator()

  ) when iterating over collections
• Avoid manual offset/limit pagination loops unless a resource genuinely lacks an iterator
• Use

  for await...of

  to consume async iterators

• Prefer

  buildBlockRecord()

  when creating block records for the simplified API
• Import it from the same package as

  buildClient

• Catch

  ApiError

  for API failures — it provides

  .errors

  getter and

  .findError()

  method
• Catch

  TimeoutError

  for request timeouts in long-running or request-heavy flows
• Import both from the same package as

  buildClient

• Follow the TypeScript strictness rules: no

  as unknown as

  , no unnecessary

  as

  casts
• Let TypeScript infer types wherever possible
• Use

  import type { ... }

  for type-only imports

1. Project-awareness bootstrap — Confirm the repo has the

   datocms

   npm package installed and the project is linked (

   datocms.config.json

   with a

   siteId

   ,

   npx datocms whoami

   succeeds). If not, the final proposal must include the install + login + link sequence before any CMA operation. For interactive / one-off tasks the deliverable should be a

   cma:call

   /

   cma:script

   invocation (shapes in Step 4), not a

   buildClient()

   script that requires a token in

   .env

   . Only when the code will run unattended (CI, server-side app, long-lived automation) should a token-in-env solution be presented — and in that case the token must have CMA access enabled and the role permissions the task needs. Schema changes require a role with

   can_edit_schema: true

   .
2. Environment targeting — If working with a sandbox, ensure the

   environment

   config option is set
3. Error handling — Ensure

   ApiError

   is caught at appropriate boundaries
4. Pagination — If the solution iterates a collection that could exceed a single page, prefer

   listPagedIterator()

5. Type safety — Ensure no type assertions (

   as

   ) are used to silence errors
6. Imports — Ensure all imports come from the correct package (the one detected in Step 1)
7. Generated types — If the solution intentionally uses generated CMA types (

   cma-types.ts

   ), ensure the chosen path is typed end to end: simplified API generics by default, or

   raw*()

   /

   RawApiTypes.Item<>

   only when raw payload access is intentional