Apps are published with the Examplary CLI. It builds your app, uploads its files, and publishes the new version, which workspaces then use right away.
Signing in
The CLI publishes as you, so you'll need to be an admin of your workspace. Sign in once in the browser:
npx @examplary/cli logindev asks you to sign in when you haven't yet, and npx @examplary/cli logout signs you out again. Where there's no browser, like in CI, use an admin's API key from the settings page of your Examplary account instead: pass it with --key, or set the EXAMPLARY_API_KEY environment variable.
Trying out your app
While you work on your app, run this in its folder:
npx @examplary/cli devThis publishes your own private copy of the app, installs it in your workspace, and opens Examplary in your browser. Whenever you save a file, the copy is updated. While it's installed, it takes the place of the app itself in your workspace, and its hooks get the app's secrets.
The developer toolbar in the browser shows whether it's still connected to dev, with a button to reload once something changed. It has a few panels for your app:
- Dev app: its capabilities, settings and hooks, and a switch to reload the page by itself whenever something changed.
- Hook calls: the latest calls of its hooks, with their arguments, result and logs.
- Cron jobs: its cron jobs, with a button to run one now.
- App storage: the documents it keeps in storage.
Press Ctrl + C to stop: the copy is then removed from your workspace.
Validating your app
To check your app without publishing it, run this in its folder:
npx @examplary/cli validateThis loads app.ts, checks the app's definition, and bundles its hooks and components to make sure they compile. For question types, it also runs the responseProcessing.testCases you defined, and warns when a component is larger than 100 kB. It's a good check to run on pull requests: inside GitHub Actions, warnings show up as annotations on the files.
To see exactly what would be uploaded, run npx @examplary/cli package. It writes the bundles, the other files, and the app's definition (app.json) to a .bundled folder.
Publishing
npx @examplary/cli publishPublishing the app again creates a new version, unless nothing changed since the last one. Workspaces that installed it keep their settings and get the new version straight away, or, for a public app, once it's been reviewed. That includes its question types.
To publish an app in a CI environment, make sure the EXAMPLARY_API_KEY environment variable is set with an admin API key, then run npx @examplary/cli publish.
To set a secret, publish the app first, then run:
npx @examplary/cli set-secret ACME_CLIENT_SECRET "..."Public apps
By default, an app is only available in your own workspace. Set public: true to let every Examplary workspace find and install it:
const app = defineApp({
id: "acme.gradebook",
// ...
public: true,
});Public apps run code in other workspaces, and their question types show up in the public question type library, so their new versions are reviewed by the Examplary team before they're used, in your own workspace too. You'll get an email when a version enters review, and another once it's approved or rejected. Until then, every workspace keeps using the last approved version. Once an app is public it can't be made private again: publishing a version with public: false is refused. To try out a new version before submitting it, use dev.
Retiring an app
To stop new workspaces from installing your app, publish a new version with deprecated: true. Workspaces that already installed it keep using it.
You can only delete an app (DELETE /apps/{id}) once no workspace has it installed, and never while it's preinstalled; until then the API answers with a 409. Deprecate it instead.
Retiring a question type
To retire one of your app's question types, set deprecated: true on its definition, or leave it out of the app, and publish a new version. Existing questions of that type keep rendering, grading and regenerating everywhere, but no new questions of that type can be created.
Deprecate rather than hide: a public app can't be made private again, because that would stop other workspaces from resolving the definitions of questions they already have, so those questions stop rendering.
Publishing on push to main
You can publish your app from CI, for example with a GitHub Actions workflow:
name: Publish to Examplary
on:
push:
branches:
- main
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 24
- run: npm ci
- run: npx @examplary/cli publish
env:
EXAMPLARY_API_KEY: ${{ secrets.EXAMPLARY_API_KEY }}