Install and use the new sf Sliick CLI plugin

Sliick Docs templates are data, not metadata. They live as Template__c rows inside the managed package, which means a Change Set or sf project deploy will not move them between orgs. Until now the workflow was to author in production or to use the in-org Export/Import modal for one-off moves. Neither of those scales to a real release pipeline.

The new @sliick/sfdx-plugin closes that gap. It is a thin sf CLI plugin that wraps the TemplatePortabilityRest resource shipped in Sliick Docs v1.6, and it gives you the same promotion model you already use for Apex and LWC: author in a staging org, export to a portable .sdt artefact, commit to git, and let CI import to production.

This guide walks through the install, the authentication model, the four commands you will actually use day to day, and a working GitHub Actions pipeline.

Prerequisites

Before you install, confirm three things:

• Salesforce CLI sf v2 or later. Run sf --version to check.
• Node.js 18 or later. The plugin is published as a standard oclif package.
• Sliick Docs 1.6.0 or later installed in every org you intend to target. The plugin checks the package version at runtime via the /version endpoint and refuses to run against older installs. If you are still on 1.5, see the Sliick Docs v1.6 release notes for the upgrade path.

The user that authenticates to each org must have the Sliick_Docs_Admin permission set assigned. The same permission set already gates the in-org Export/Import modal, so most Sliick Docs admins already have it.

Install

sf plugins install @Sliick/sfdx-plugin

Verify the install:

sf Sliick docs --help

You should see the export, import, diff, validate, and template list commands listed. If sf reports the plugin is not found, run sf plugins to confirm the install registered, then restart your terminal so the new commands are on the PATH.

Authentication

The plugin does not introduce a new auth model. It inherits whatever sf session is active for the target org alias, which means the same login command you already use for sf project deploy works here.

Interactive (developer laptop):

sf org login web --alias staging
sf org login web --alias prod

Headless (CI runner):

sf org login jwt \
  --username admin@mycompany.com \
  --jwt-key-file server.key \
  --client-id <connected-app-client-id> \
  --alias prod

Every plugin command accepts --target-org <alias> (or -o <alias>) and uses that alias’s stored session. There is no separate token to manage and no secret to rotate beyond the standard sf auth.

The promotion model

Author in staging org -> Export -> Commit .sdt to git -> CI imports to prod

The unit of promotion is a .sdt file. It is a Sliick Docs Template (.sdt) archive that carries:

• Template metadata: name, configuration, editor state.
• Bundle membership.
• Image files: watermark and image-block assets, at any size.
• Optionally, version history (with --include-history).

You commit .sdt files to git alongside your Apex and LWC. Each file is opaque and is reviewed by proofing the template in the org before export, not by reading the binary. Themes and org-wide settings (Docs_Theme__mdt, Docs_Setting__mdt) are custom metadata and continue to travel via Change Sets or sf project deploy. The plugin handles templates and bundles only.

The four commands you will actually use

Export: pull templates out of an org

# Everything in the org
sf Sliick docs export --target-org staging --all --out templates/

# A specific list of templates
sf Sliick docs export --target-org staging --templates Invoice,Quote --out templates/

# A whole bundle (member templates are included by default)
sf Sliick docs export --target-org staging --bundles "Onboarding Pack" --out templates/

# Skip image files for a fast, text-only diff
sf Sliick docs export --target-org staging --all --no-files --out templates/

The export reads templates over the REST surface and downloads any associated image files through the Salesforce REST Files API. That last detail matters: the Files API path means watermarks and image blocks of any size pass through cleanly, with no Apex heap limit to trip over.

Import: push a .sdt into the target org

# Single artefact
sf Sliick docs import templates/invoice.sdt --target-org prod

# A directory of artefacts, processed in lexical order, one transaction per file
sf Sliick docs import templates/ --target-org prod

# Dry run: see what would change, write nothing
sf Sliick docs import templates/invoice.sdt --target-org prod --dry-run

# CI mode: fail the build on any warning
sf Sliick docs import templates/ --target-org prod --fail-on-warnings

# Import and publish in one step
sf Sliick docs import templates/invoice.sdt --target-org prod --auto-publish

The defaults are tuned for CI:

• --match-by external-id matches incoming templates to existing rows by their portable identity, so an Invoice exported from staging lands on the same Invoice in prod even if the record Id differs.
• --on-conflict update updates the existing template’s draft version. Published versions are never silently overwritten.

By default, an import lands templates as a draft and waits for an admin to publish in-org. Pass --auto-publish to publish automatically. Auto-publish is validation-gated and atomic: if any template in the artefact fails validation in the target org (for example, a merge field references a field that does not exist on the target sObject), the entire import rolls back. Nothing is imported, nothing is published. That is what makes it safe to wire into a CI pipeline.

Diff: preview the changes before you run them

sf Sliick docs diff templates/invoice.sdt --target-org prod

The output marks each template and bundle as CREATE, UPDATE, or SKIP against the target org. This is the command you run during a release review, and the one you wire into a PR comment if you want reviewers to see the proposed change set before approving the merge.

Validate: check the artefact without an org

sf Sliick docs validate templates/invoice.sdt

Validate runs offline. It checks the file structure, the schema of the metadata files, and the integrity of any embedded image references. It is fast and it is the first thing you should run in CI, before you spend an authenticated call on diff or import.

Live record query

If you just want to see what is in an org without exporting:

sf Sliick docs template list --target-org prod
sf Sliick docs template list --target-org prod --json

The list shows each template’s External Id, its active (published) version, the latest draft version, and whether a draft is sitting unpublished. The --json flag is the one you want for any scripted use.

A working CI pipeline

The promotion model assumes git is the source of truth. The pipeline below runs on every push to main that touches the templates/ directory: it installs the CLI and plugin, authenticates to prod, validates the artefacts offline, previews the diff against the target org, then imports with --fail-on-warnings so any warning rolls the build back.

name: Promote templates to prod

on:
  push:
    branches: [main]
    paths: ['templates/**']

jobs:
  promote:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install sf CLI and plugin
        run: |
          npm install -g @salesforce/cli
          sf plugins install @Sliick/sfdx-plugin

      - name: Authenticate
        run: |
          echo "${{ secrets.SFDX_AUTH_URL }}" | sf org login sfdx-url --sfdx-url-stdin --alias prod

      - name: Validate artefacts
        run: sf Sliick docs validate templates/

      - name: Preview changes
        run: sf Sliick docs diff templates/ --target-org prod

      - name: Import
        run: sf Sliick docs import templates/ --target-org prod --fail-on-warnings

If you prefer JWT auth over sfdx-url, swap the Authenticate step:

      - name: Authenticate (JWT)
        run: |
          echo "${{ secrets.JWT_KEY }}" > server.key
          sf org login jwt \
            --username ${{ secrets.SF_USERNAME }} \
            --jwt-key-file server.key \
            --client-id ${{ secrets.SF_CLIENT_ID }} \
            --alias prod

Exit codes

Every command exits cleanly so you can gate on it from a shell or CI step.

The CI-style guard is the one-liner you expect:

sf Sliick docs import templates/ --target-org prod --fail-on-warnings || exit 1

A few questions worth answering up front

Can I edit a .sdt by hand? No. The artefact is a post-proof binary. Author in the in-org editor, proof there, then export. Hand-editing a .sdt is not a supported workflow and will not survive a re-import.

Can I re-import to the org I exported from? Yes. With the default --match-by external-id --on-conflict update, a round trip updates the existing templates in place. This is useful for a few patterns: refreshing a staging org from a known-good production export, or rebuilding a scratch org from the committed .sdt set.

What happens with a very large watermark or image block? Nothing special. The plugin streams images via the REST Files API, which has no Apex heap limit. The image size that breaks the in-org Export modal will pass through the plugin without complaint.

Do I need this plugin at all? For a one-off move between two orgs you control, no. The in-org Export/Import modal is still there and is the right tool for a single template. The plugin exists for repeatable pipelines: git as source of truth, automated promotion, --fail-on-warnings gates, and CI artefacts that survive a personnel change.

What changes about the way you ship templates

Before v1.6 and this plugin, the honest answer for most teams was that templates were authored in production and that any “staging” copy was kept in sync by hand. That is a fine workflow when one admin owns the templates, and it falls apart the moment you want a review step, a rollback story, or a second person involved.

The plugin does not invent a new process. It lets templates use the process you already run for code: a branch, a PR, a diff, an automated import, an audit log. The artefact is portable, the auth model is the one you already manage, and the failure mode (atomic rollback on validation failure) is the one CI expects.

If you are still on Sliick Docs 1.5, start with the v1.6 release notes for the upgrade path and the portability foundation the plugin sits on. If you are on 1.6 already, install the plugin, export your first template, and put the .sdt in a branch. The rest of the pipeline writes itself.