Audited workflows

Localized content

For localized resources, --locale selects the content locale. The CLI sends it as content_locale, so reads and writes address that locale rather than filtering records by a generic locale query.

This applies to pages, menus, products, collections, blogs and posts, notifications, channel entries, and shipping rates:

nimbu pages get --page=about --locale=nl-BE
printf '%s\n' '{"seo_title":"Over ons"}' |
  nimbu pages update --page=about --locale=nl-BE --file=-
nimbu products update --product=shirt --locale=fr name="Chemise"
nimbu blogs posts update --blog=news --post=launch --locale=nl title="Lancering"

Use canonical locale casing in scripts: nl-BE, zh-Hant-TW. Translation assignment keys also accept forms such as nl_BE and normalize them to nl-BE; equivalent hyphen/underscore forms match when projecting output.

--json keeps the complete server representation, including every translations block. Human and --plain output overlay the selected locale onto the displayed fields and fall back to the top-level value when that translation is absent.

Write one or several locales

Use --locale for a single-locale write. Where a resource accepts a translations payload, send several locales in one request:

nimbu pages update --page=about \
  'translations:={"nl":{"seo_title":"Over ons"},"fr":{"seo_title":"À propos"}}'

nimbu menus update --menu=main --file=menu-translations.json

Top-level translations:=... is allowed inline for pages and menus. Other nested page or menu edits require --file; inline updates are intentionally limited to shallow fields. Use --replace --file=page.json only when replacing the page canvases, and review its destructive guards first.

For string translations, create --file accepts one object or an array:

[
  {
    "key": "checkout.submit",
    "values": {
      "nl-BE": "Bestellen",
      "fr": "Commander"
    }
  },
  {
    "key": "checkout.cancel",
    "values": {
      "nl-BE": "Annuleren",
      "fr": "Annuler"
    }
  }
]

nimbu translations create --file=translations.json
nimbu translations create key=home.title nl=Welkom fr=Bienvenue

The second form is shorthand for values.nl and values.fr.

Copy localized content

The native copy commands preserve localized payloads:

nimbu products copy --from=staging --to=production --json
nimbu blogs copy --from=staging --to=production --only=news --json
nimbu sites copy --from=staging --to=production --dry-run --json

Product copy maps localized built-in and custom fields to the target site's configured locales and preserves localized variants. Blog copy matches blogs and posts in the target default locale while preserving translation maps, SEO fields, and other writable fields. Both copy flows require explicit default locales on both sites, and the target default must exist on the source. Full site copy uses these localized copy stages and includes the complete consent configuration. With --allow-errors, consent is skipped with a warning if its page-backed privacy policy could not be copied.

Consent configuration

Manage the complete consent configuration without raw API calls:

nimbu settings consent config get --json
nimbu settings consent config update enabled:=true privacy_policy_url.nl=/privacybeleid
nimbu --force settings consent config replace --file=consent.json
nimbu settings consent config copy --from=staging --to=production --dry-run --json

update patches selected fields. replace requires an explicit JSON file or --file=- plus --force because it replaces the whole configuration. copy resolves page references on the target site and preserves localized and unknown fields.

Shipping rates

Shipping rates have native CRUD commands:

nimbu shipping-rates list --locale=nl --json
nimbu shipping-rates get --rate=RATE_ID --locale=nl
nimbu shipping-rates create name=Express price:=12.5 region_id=REGION_ID
nimbu shipping-rates update --rate=RATE_ID --locale=nl name=Spoed
nimbu shipping-rates update --rate=RATE_ID --locale=fr name=Express
nimbu --force shipping-rates delete --rate=RATE_ID

There is no shipping-rates count or shipping-rates copy. The API does not accept a nested translations payload for shipping rates. Create the rate once, then repeat update --rate with --locale for each translation.

Region IDs are opaque and site-specific. For that reason, sites copy inspects source shipping rates but does not copy them. If it finds any, its structured result and progress output include an explicit warning with the number skipped.

Page content

Edit page content with the surgical verbs instead of round-tripping the whole document. Learn the page structure first, then change only what you need:

# Template schema, then the page skeleton (ids, positions, select options)
nimbu pages schema --page=about/team --json
nimbu pages get --page=about/team --shape
nimbu pages get --page=about/team --outline   # one line per editable, paths usable with --path
nimbu pages get --page=about/team --compact --json

# One change per command; --dry-run resolves paths and prints the operations
nimbu pages set --page=about/team --path='Blokken[0].Title' --dry-run --diff "Our team"
nimbu pages set --page=about/team --path=title "Our team"
nimbu pages insert --page=about/team --path=Blokken --slug=quote --position=0
nimbu pages move --page=about/team --path='Blokken[2]' --position=0
nimbu pages delete-block --page=about/team --path='Blokken[slug=quote]'

# Several changes in one request (max 10 operations)
nimbu pages batch --page=about/team --file=ops.json --dry-run
nimbu pages batch --page=about/team --file=ops.json

Human paths are 0-based (Blokken[2].Title, Blokken[id=<id>], Blokken[slug=hero]); a leading / is a raw API path. pages batch takes {"operations":[...]} or a bare array of set, insert, delete, and move operations and is atomic by default. --no-atomic allows partial success on live pages; draft batches are always atomic. Run nimbu pages batch --help for the operation format.

The CLI sends the page ETag as If-Match on live writes. If the page changed in the meantime, it reloads the page, re-resolves the paths, and retries once.

Drafts and preview

Add --draft to set, insert, move, delete-block, or batch to write to the page draft instead of the live page. Then preview and publish:

nimbu pages set --page=about/team --path=title --draft "Coming soon"
nimbu pages draft get --page=about/team --shape
nimbu pages draft preview-url --page=about/team --open
nimbu pages draft publish --page=about/team
nimbu --force pages draft discard --page=about/team

pages draft save --file replaces the whole draft; pages draft batch applies operations to it. preview-url prints a preview link that expires after 24 hours. If the live page changed after the draft was based on it, publish fails with 409 draft_base_changed: rerun it with --confirm to overwrite the live content, or discard the draft (--force required) and start over. To browse drafts through the local simulator, run nimbu server --draft=about/team (repeatable).

pages update --file remains the whole-document fallback and merges by default. --dry-run fetches, merges, and prints the PATCH body without sending it. For the underlying endpoints, see Working with Pages via the API. Read that guide before using pages update --replace.

Role membership

Use roles customers to change who belongs to a role:

nimbu roles customers add --role=ROLE_ID --customer=CUSTOMER_ID
nimbu roles customers remove --role=ROLE_ID --customer=CUSTOMER_ID
nimbu roles customers set --role=ROLE_ID --customer=ID_1 --customer=ID_2

A plain customers array in roles update replaces the whole member list, so a stale or partial list silently drops members. The roles customers commands read the current list, apply your change, write the full list back, and read it again to verify. remove and set require --force when they would drop more than half of the members. set needs at least one --customer; to empty a role, send {"customers": []} with nimbu --force roles update. roles update --dry-run prints the request body and projected member counts without writing.

Other native workflows

nimbu products attachments list --product=shirt
nimbu products attachments download --product=shirt --attachment=manual --output=manual.pdf
nimbu uploads download --id=UPLOAD_ID --output=image.jpg
nimbu apps code get --app=storefront --filename=main.js
nimbu pages versions list --page=about
nimbu customers roles set --customer=CUSTOMER_ID --role=member --role=buyer
nimbu settings get --section=shipping
nimbu settings update --section=shipping enabled:=true
nimbu announcements list --all
nimbu domain-registrations list --all

Customer role add and remove derive direct membership from the role resources, so inherited roles are not promoted to direct assignments. Like roles customers, they use a verified read-modify-write cycle; concurrent changes can race until the API offers conditional or atomic mutations.

themes push --only and themes sync --only also upload the local Liquid snippets and layouts that the selected files include, in dependency order. Pass --no-deps to upload only the selected files:

nimbu themes push --only=templates/page.liquid --dry-run
nimbu themes push --only=templates/page.liquid --no-deps

To deploy channel, product, and customer schemas together with cloud code and the theme, see Schemas and releases.