SDK CLI

@cachely-io/sdk ships a deterministic CLI for bootstrapping Cachely in your project. It detects your framework and CMS provider, generates a typed helper file, and updates .env.example — without touching any existing source files.

Commands

npx @cachely-io/sdk <command>

Commands:
  setup                          Generic helper-file generation for any framework + CMS.
  setup --provider prismic       Provider-specific onboarding (Nuxt + Prismic) — same as below.
  setup prismic                  Provider-specific onboarding (Nuxt + Prismic).
  init prismic                   Alias for `setup prismic`.
  setup --provider contentful    Provider-specific onboarding (Contentful).
  setup contentful               Same as above.
  init                           Print available providers for provider-specific onboarding.

Since 0.12.0: setup --provider prismic and setup prismic are equivalent. Earlier versions dropped the flag form to the generic helper-only flow — that bug is fixed.

Generic setup

Use this path for any framework and CMS combination:

npx @cachely-io/sdk setup

The CLI:

1. Detects your framework — Next.js, Nuxt, Vite, or generic
2. Detects your CMS provider — Prismic, Contentful, Sanity, Storyblok, Shopify, or generic
3. Detects your package manager — pnpm, npm, yarn, or bun
4. Generates a typed helper file
5. Adds CACHELY_PROXY_URL to .env.example
6. Installs @cachely-io/sdk

Generated helper locations

Flags

Provider-specific flags (Prismic onboarder):

Examples

# Auto-detect everything (interactive)
npx @cachely-io/sdk setup

# Prismic + Nuxt (rich onboarder, both forms equivalent since 0.12.0)
npx @cachely-io/sdk setup --provider prismic --tenant my-project --yes
npx @cachely-io/sdk setup prismic --tenant my-project --yes

# Preview without writing
npx @cachely-io/sdk setup --dry-run --provider prismic --tenant my-project

# Prismic with AI Transforms doc + experiments wiring
npx @cachely-io/sdk setup --provider prismic --tenant my-project --transforms --experiments --yes

# Force composables-only (do not touch existing Prismic client)
npx @cachely-io/sdk setup --provider prismic --tenant my-project --composables --yes

# Non-interactive CI mode (Next + Contentful — routes to the Contentful onboarder since 0.12.0)
npx @cachely-io/sdk setup --yes --tenant my-project --provider contentful --framework next

Provider-specific onboarding

For a more guided, CMS-specific setup, use the provider commands.

Prismic onboarding

All three of these commands are equivalent — they reach the same rich onboarder (since 0.12.0):

npx @cachely-io/sdk setup --provider prismic --tenant my-project
npx @cachely-io/sdk setup prismic --tenant my-project
npx @cachely-io/sdk init prismic --tenant my-project

What Prismic onboarding does

1. Detects a Nuxt project — looks for nuxt.config.ts, nuxt.config.js, or nuxt.config.mjs.
2. Detects Prismic — checks for @prismicio/client or @prismicio/nuxt in dependencies.
3. Reads repositoryName from slicemachine.config.json.
4. Generates composables/useCachelyPrismicClient.ts — the primary integration surface:

   import { createCachelyPrismicClient } from "@cachely-io/sdk/prismic"
   import { repositoryName } from "~/slicemachine.config.json"
   
   export function useCachelyPrismicClient() {
     return createCachelyPrismicClient({
       repositoryName,
       tenant: "my-project",
     })
   }
   

   Use it in pages: const client = useCachelyPrismicClient(). On Nuxt 4 layouts, writes to app/composables/ instead. Picks .ts or .js based on existing folder contents.
5. On greenfield or trivially-patchable projects, also writes app/prismic/client.js (the canonical user-defined client) and patches config/nuxt/prismic.{js,ts}:

   // app/prismic/client.js
   import { createClient } from "@prismicio/client"
   import { createCachelyFetch } from "@cachely-io/sdk"
   import { repositoryName } from "~/slicemachine.config.json"
   
   const cachelyFetch = createCachelyFetch({ tenant: "my-project", provider: "prismic" })
   export default createClient(repositoryName, { fetch: cachelyFetch })
   

   // config/nuxt/prismic.js
   export default {
     endpoint: config.repositoryName,
     client: "~/app/prismic/client"
   }
   

   With both in place, usePrismic().client is also routed through Cachely.
6. On complex existing clients (token, routes, custom fetch, etc.), the file is not modified. The CLI prints a loud warning + manual patch instructions instead. Re-run with --patch-client to force-attempt the canonical write.
7. Writes/merges cachely.config.json in the project root:

   {
     "provider": "prismic",
     "framework": "nuxt",
     "repositoryName": "your-repo",
     "apiOrigin": "https://your-repo.cdn.prismic.io",
     "cachelyEndpoint": "https://my-project.cachely.io/~api/api/v2",
     "recommendedClient": "~/app/prismic/client",
     "integration": "both",
     "transforms": false,
     "experiments": false
   }
   

   Tooling manifest only — not a runtime import.
8. Installs @cachely-io/sdk if it is not already in package.json.
9. Does not modify nuxt.config.{ts,js} — prints the snippet to add runtimeConfig.public.cachelyProxyUrl instead. Same policy applies to the cachely: { tenant } block when --experiments is enabled.
10. Does not generate composables/useCachely.ts — that generic helper caused confusion (generated, never called) and is no longer emitted by the Prismic onboarder. Run plain npx @cachely-io/sdk setup (no provider) if you specifically want the lower-level fetch helper.

Integration-mode behaviour matrix

In interactive mode (no --yes), you are prompted for: integration mode, transforms, experiments.

Supported flags

--patch-client --experiments without --composables is not recommended. The canonical app/prismic/client.js template uses createCachelyFetch which does not accept an experiments tracker, so only the Nuxt module's autoTrack() will work; per-response assignment-header capture requires the composable surface. The CLI prints a loud warning when this combination is requested.

Dry-run

npx @cachely-io/sdk setup --provider prismic --dry-run --tenant my-project

Prints all planned file changes without writing anything.

After Prismic onboarding

Use the generated composable in pages:

<script setup lang="ts">
const client = useCachelyPrismicClient()
const { data: page } = await useAsyncData('home', () => client.getSingle('page_home'))
</script>

If the canonical client was also written (greenfield / trivially-patchable case), const { client } = usePrismic() is routed through Cachely too. If you opted into composables-only, swap any remaining usePrismic().client callers to useCachelyPrismicClient().

Clear Nuxt's generated cache and restart:

rm -rf .nuxt
npm run dev

If the canonical client was patched, the startup log includes:

Using user-defined `client` at `~/app/prismic/client.js`

In DevTools, Prismic API requests should go to https://<tenant>.cachely.io/~api/api/v2/... and asset URLs in API JSON should be rewritten to https://<tenant>.cachely.io/<repositoryName>/....

Prismic troubleshooting

• I ran setup but requests still hit Prismic. Pages still call usePrismic().client or custom /api/cms/... endpoints. Switch them to const client = useCachelyPrismicClient(). If you opted into the canonical client path, verify config/nuxt/prismic.js contains client: "~/app/prismic/client".
• useCachelyExperiments is not defined. The Cachely Nuxt module isn't registered. Add modules: ['@cachely-io/sdk/nuxt'] and cachely: { tenant: '<slug>' } to nuxt.config.
• Setup did not modify my existing client. By design — your existing client has custom options. Use the generated composable from your pages, or manually apply the printed patch instructions.
• Still seeing cdn.prismic.io. Delete .nuxt, restart dev, and confirm config/nuxt/prismic.js includes client: "~/app/prismic/client".
• "A repository name is required..." Endpoint replacement was used in a hand-written setup. Restore endpoint: config.repositoryName and use the client file with createCachelyFetch.
• Asset URLs still point at images.prismic.io. First confirm API requests go through Cachely, then check that API response rewriting is enabled.
• AI Transforms are not applying. Requests reach Cachely but come back untransformed because no transform profile was passed for that Prismic call. Pass it per-call:

  client.getSingle('page_home', { cachely: { transform: 'serbian' } })
  

  The profile must be active in the dashboard (drafts only run in preview). Set transform on createCachelyPrismicClient({ ... }) to apply it to every call from that client; per-call cachely: { transform: null } disables the default for one request. The cachely namespace is stripped before params reach @prismicio/client.

Contentful onboarding

npx @cachely-io/sdk setup --provider contentful --tenant my-project
npx @cachely-io/sdk setup contentful --tenant my-project
npx @cachely-io/sdk init contentful --tenant my-project

Detects a Contentful client file under plugins/, services/, lib/, utils/, or src/{lib,services}/ and safely patches the single safe shape (one createClient(<bare-identifier>) call referencing a top-level config object with no existing adapter: key). More complex files are left untouched with manual instructions printed.

Sanity & Storyblok — detect + status-only

npx @cachely-io/sdk setup --provider sanity --tenant my-project
npx @cachely-io/sdk setup --provider storyblok --tenant my-project

These detect dependencies and metadata into cachely.config.json but do not modify any client file or install the SDK. Runtime SDK routing for these providers ships in a future release.

Manual install

If you prefer not to run the CLI:

npm install @cachely-io/sdk
# or: pnpm add @cachely-io/sdk
# or: yarn add @cachely-io/sdk
# or: bun add @cachely-io/sdk

Then write your own helper using createCachelyFetch. See the SDK reference for the full API.