Skip to content
littleworksdocs

Explore the documentation

Meet LittleworksA little backend for what you’re building on Shopify.Littleworks or your own appWhat it takes to give a Shopify feature a backend: with Littleworks, or with a custom app you build and run yourself.Connect to LittleworksChoose the CLI, a plugin, or a remote MCP connection.CLIConnect from your terminal with Shopify approval and no manual tokens.Claude pluginThe Littleworks MCP connection and agent guidance in one package.OpenAI pluginThe Littleworks MCP connection and agent guidance in one package.MCP with OAuthConnect a compatible client directly, without a marketplace plugin.Build with an agentThe operating guide for agents building on Shopify with Littleworks.Write a workA JavaScript handler, a small manifest, and a version you test and then publish.Keep secretsEncrypted credentials, shared across your store’s works.Call external servicesMake public HTTPS API requests from a work using http.fetch().Store dataDocument collections with a small API, scoped automatically to the work that uses them.Call ShopifyCall Shopify’s Admin and Storefront GraphQL APIs with credentials held by Littleworks.Store filesKeep uploads such as artwork and photos in the merchant’s Shopify Files, uploaded by the browser straight to Shopify.Expose an endpointConnect an existing frontend to a work through a small JSON API.Customer access and invitationsRequire a signed-in shopper or a narrow, expiring invitation before a work runs.RecipesUseful things to build for your store, with the backend already taken care of.Product reviewsCollect customer reviews, verify purchases, and publish approved content directly into your Shopify theme.Customer wishlistsGive signed-in customers a persistent list of products they can revisit across devices.Customer quote requestsCollect a customer’s products, quantities, and requirements without turning a request into an order.Back-in-stock alertsCollect confirmed signups on sold-out variants, email them through your own provider when stock returns, and see every signup and send in your admin.Transactional emailSend email from your works through your own provider, never twice for the same thing, and see what was sent and what failed.Build a merchant pageDescribe your records and what merchants do with them; Littleworks renders a native Shopify admin page.Run works on their ownRun a work when something happens in the store, on a schedule, or from a Shopify Flow workflow.Run background jobsQueue runs for later or in the background: fan out to thousands of customers, import in pages, follow up days later, and retry what fails.MCP tool referenceTools to inspect, deploy, run, and organize the backend for a connected store.Usage and allowancesSee what your works use, how much capacity remains, and when allowances reset.Inspect and troubleshootFind the relevant run, understand the failure, and make the next change deliberately.Limits and securityThe current runtime boundaries, data isolation model, and execution allowances.
Shopify admin
Browse documentation
Connect
Markdown

CLI

Connect from your terminal with Shopify approval and no manual tokens.

Install and sign in

Use Node.js 22 or newer. Install @littleworks/cli from npm.

Install the CLI
npm install -g @littleworks/cli
littleworks skill install
littleworks login

Login opens your browser. Enter your store’s myshopify.com domain and approve access inside Shopify. The CLI then shows the connected store. Login waits up to 10 minutes for approval. It also prints the authorization link, which you can open yourself on the same computer if no browser opens. littleworks help lists every command and littleworks <command> --help explains one without contacting your store. Agents should read the agent guide before building.

littleworks skill install adds the Littleworks skill, which teaches your agent how to build with Littleworks, to the shared Agent Skills folder (~/.agents/skills, read by pi and other clients) and, when Claude Code is installed, to ~/.claude/skills. Run it again after updating the CLI; littleworks context says when the installed skill is out of date. littleworks skill uninstall removes it. For theme changes, the skill recommends the Shopify CLI and Shopify’s agent skill.

Inspect before making changes

Inspect current usage and remaining allowances with littleworks call get_usage '{}'. See Usage and allowances for reset dates, shared capacity, and protection notices.

The CLI calls the same MCP tools as the plugins. littleworks context fetches the current SDK interface, limits, Shopify permissions, and available secret names directly from the connected server.

Read the connected store
littleworks context
littleworks list
littleworks get notes.save

Deploy, test and publish a work

Use your own source and manifest
littleworks check handler.ts
littleworks deploy manifest.json handler.ts
littleworks invoke notes.save '{"message":"Hello"}'
littleworks runs --test true
littleworks collections notes
littleworks test-records delete notes
littleworks publish notes.save

These are command examples, not instructions to create a sample work. deploy saves a new version: a new work is a draft whose newest version is current, and a published work gets a pending version that serves nothing until you run publish. invoke tests a draft’s newest version, runs a published work’s current version for real, and tests any other version with --version-id <version>. publish <name> [version] makes a version (by default the newest) current; rollback <name> <version> publishes an earlier one. Source is bundled locally with esbuild, then checked by the server. Packages cannot bypass runtime restrictions.

Each invoke generates an idempotency key. Supply --idempotency-key <key> when deliberately retrying the same invocation. Check for partial effects before retrying mutations.

Use the current runtime capabilities

CLI-deployed works can use document storage, secrets, and external HTTPS requests through the same runtime SDK as works deployed by a plugin. secrets.get() and http.fetch() run on the server. Test runs use the store’s real documents and secrets, and permitted Shopify and external requests reach real services.

Enter secret values in Littleworks → Works → Secrets inside Shopify. context returns names and metadata only. Never put secret values in source, prompts, stored documents, logs, or returned data. Redaction helps protect logs and diagnostics but cannot catch every transformation of a value.

Inspect logs, external requests, and data
littleworks run RUN_ID
littleworks collections
littleworks records FEATURE COLLECTION

Run details include logs, errors, and outbound request hostname, method, status, duration, and error code. Outbound request paths, query strings, headers, and bodies are excluded from diagnostics.

Use the full tool interface

Inspect with MCP tools through the CLI
littleworks call list_collections '{}'
littleworks call get_run '{"runId":"RUN_ID"}'

littleworks call accepts the exact tools and arguments in the MCP reference. Friendly commands also cover publish, pause, resume, rollback, runs, records, cache purge <name>, test-records delete [feature] and record-delete <feature> <collection> <id> <revision>. Delete test records only after the merchant agrees. Clean up a work with littleworks delete <name> <current-version>. Run littleworks help for the complete command list.

Build merchant pages

Agents build merchant pages from a short definition: the records' fields and their kinds, a pattern (queue, table, cards or board), settings, metrics and charts, each reading from page works, plus actions that run action works.

Save, check and publish a page
littleworks view-suggest reviews.list
littleworks view-save reviews.view.json
littleworks views
littleworks view-publish reviews DRAFT_VERSION null reviews.list=VERSION reviews.stats=VERSION reviews.moderate=VERSION

view-save takes a file holding {definition, baseVersion} (null for a new page; add --validate-only to check without saving). It returns the draft's version, its manageUrl and data checks from running each data work once. view-suggest drafts a definition from what a data work returns. view-publish publishes the page and the works it uses together; append work=version pairs to publish exactly what you tested. view-get, view-unpublish and view-delete complete the set.

Test and watch automations

Event and schedule works run on their own once published (automations). Test them as drafts with the input a real delivery builds, then watch what happened after publishing.

Sample events, schedule ticks and deliveries
littleworks invoke back_in_stock.notify --event inventory_levels/update --payload restock.json
littleworks invoke digest.daily --schedule --at 2026-10-05T08:00:00-04:00
littleworks events back_in_stock.notify

Test and watch background jobs

Background jobs run job works that other works queue. Test a job work with its input and a sample job, then list, cancel or retry jobs.

Job samples, lists, cancelling and retries
littleworks invoke back_in_stock.send '{"productId":"gid://shopify/Product/1"}' --job
littleworks jobs back_in_stock.send --status failed
littleworks jobs retry JOB_ID
littleworks jobs cancel back_in_stock.send --key restock:123

Connect another store

Separate named connections
littleworks login --profile second-store
littleworks context --profile second-store
littleworks logout --profile second-store

Each profile holds one connection. OAuth credentials are saved in a private file under ~/.littleworks, outside your project. Commands using the same profile can run in parallel. Only sign-in, sign-out and token refresh wait for each other, so a rotating refresh token is never spent twice. Do not share or commit these files. Logout revokes the connection and removes its local credentials.

Export your data and code

Export the whole store to a directory
littleworks export
littleworks export ./backups/my-store

One command writes everything the connected store holds in Littleworks as plain files, by default to littleworks-export-<store>-<date>:

  • collections/<feature>/<collection>.json: every record with its id, data, revision, createdAt, updatedAt, expiresAt and test flag.
  • works/<name>/work.json: status, current and newest version IDs and the saved version list. current/ holds the manifest and source of the version serving real traffic; newest/ appears when a newer version is pending. Redeploy one with littleworks deploy manifest.json source.js.
  • views/<name>/draft.json and published.json: each view’s definitions.
  • littleworks-export.json: the store, export time, counts, CLI version, the names of your secrets and any item that failed.

Progress goes to stderr and a summary to stdout. A failed item is listed and the rest continue; the command exits with status 1 so scripts notice. Re-running into the same directory refreshes it: files for deleted works and views are removed, a failed item keeps its previous copy, and other files are left alone. A directory that is not a Littleworks export is never written to. Secret values, OAuth credentials and Shopify tokens are never exported; credentials placed in documents or source would be, so always use the secrets store. Records are read page by page while works keep running, so pause writes if you need a consistent snapshot. Run logs are not included; littleworks runs and littleworks run read them for seven days.

Keep the CLI up to date

Install the latest release
npm install -g @littleworks/cli@latest
littleworks --version

Server-side capabilities and context stay current through MCP. Local check rules and the packaged help and README come from your installed CLI version. Deployment always checks code against the server's current rules.