@manta-eu/cli 0.0.0-stage → 0.5.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Manta AI AS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,114 @@
-# Temporary Holding Version
+# @manta-eu/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The `manta` CLI keeps what a Manta datastore holds in line with files you track in git. It covers your app's
+vocabulary (the classes and properties your app adds to the knowledge graph) and the SHACL shapes for those classes.
+
+Documentation: [developers.manta.eu](https://developers.manta.eu)
+
+## Push your vocabulary
+
+Keep the vocabulary as a Turtle file in your repo, under a namespace your app owns:
+
+```turtle
+@prefix todo: <https://todomvc.example/vocab#> .
+
+todo:Todo a rdfs:Class ; rdfs:label "Todo" ; rdfs:comment "Something to do." .
+todo:title a rdf:Property ; rdfs:domain todo:Todo ; rdfs:range xsd:string ; rdfs:label "Title" .
+```
+
+Then make the datastore hold exactly what it declares:
+
+```shell
+pnpm manta ontology push manta/ontology.ttl --datastore your-datastore --name todomvc \
+  --namespace https://todomvc.example/vocab#
+```
+
+- **Declarative.** The datastore ends up with the triples the file declares, and nothing it no longer declares.
+  Running it again changes nothing, so it fits a CI step after every merge.
+- **Your own graph.** Each `--name` gets its own named graph, described as an `owl:Ontology` whose `dcterms:identifier`
+  is the name, so a push never touches the realm's ontology or another app's vocabulary. The realm's ontology is
+  redeployed independently, and your vocabulary survives that. Ontology coverage skips these graphs, so your
+  vocabulary is never counted as data.
+- **Your own namespace.** `--namespace` names the namespace your app owns. Every term the file declares must be under
+  it.
+- **Dry run.** `--dry-run` reports how many triples would be added and removed, and writes nothing.
+- **Blank nodes.** Triples on blank nodes (a list, a nested description) cannot be compared between pushes, so a file
+  with any is rewritten on every push. The result is the same graph.
+
+`manta ontology delete --datastore your-datastore --name todomvc` removes the vocabulary.
+
+## Push your shapes
+
+SHACL shapes describe a class's properties, so `manta-codegen` can generate typed schemas for it. Keep them in a second
+file, pushed under the same `--name` as your vocabulary:
+
+```turtle
+@prefix todo: <https://todomvc.example/vocab#> .
+
+todo:TodoShape a sh:NodeShape ;
+  sh:targetClass todo:Todo ;
+  sh:property [ sh:path todo:title ; sh:datatype xsd:string ; sh:maxCount 1 ] .
+```
+
+```shell
+pnpm manta shapes push manta/shapes.ttl --datastore your-datastore --name todomvc
+```
+
+- **One shapes graph.** Your shapes land in the datastore's shapes graph next to the realm's, so every reader of shapes
+  sees them. Each one is tagged with your `--name`, a push replaces only the shapes tagged with it, and a realm deploy
+  keeps them.
+- **Kept outside the datastore too.** Each push also stores a copy next to the datastore's uploads, and a realm deploy
+  puts it back, so a rebuilt datastore gets your shapes again. Only the shapes are stored: on a rebuilt datastore, push
+  your vocabulary again before you push or delete shapes as a custom app. A deploy puts your shapes back without
+  checking them again, so a realm shape added later for one of your classes sits next to yours until you push again.
+- **Classes nobody else shapes.** A shape may target your own classes or the classes your data brings in, such as one
+  Manta inferred from an upload; a shape you push for that class takes over from the inferred one the next time Manta
+  syncs the upload shapes. A class the realm's own shapes or another app's shapes already cover is refused, so your
+  shapes can never make the realm's or another app's data fail validation.
+- **Your own names.** Name your shapes in your app's own namespace. A name in a namespace Manta uses (the realm's own,
+  an integration's such as `meta:`, or RDF, RDFS, OWL, XSD or SHACL), or one the realm or another app already uses, is
+  refused.
+- **Shape predicates only.** A shapes file may use RDF, RDFS, OWL, XSD, SHACL and Dublin Core predicates, and its own.
+  Manta's own predicates, such as the tags that tell app and upload shapes apart, are refused.
+- **Declarative.** Nothing the file no longer declares is left behind, and a second push of the same file writes nothing.
+  `--dry-run` reports what would change.
+- **Your app's shapes only.** A custom app pushes or deletes shapes with its machine token, and only for a vocabulary
+  name it pushed itself. An operator may manage any app's shapes.
+
+`manta shapes delete` removes your shapes. Delete them before your vocabulary: `manta ontology delete` is refused while
+shapes pushed under the same `--name` are still in the datastore.
+
+The vocabulary push keeps the prefixes your file declares for your own namespace, so `manta-codegen` names your schemas
+after them (`todo.ts`). Declare your namespace with its prefix in the vocabulary before you push shapes for it.
+
+The command targets hiremanta.com production unless `--api-url`, `--keycloak-url` and `--keycloak-realm` name another
+deployment, as for `manta-codegen`.
+
+## What the API checks
+
+The whole push is refused, and nothing is written, when the file:
+
+- is not valid Turtle, declares nothing, or is larger than 1 MiB;
+- declares a term outside `--namespace`, or names a namespace that overlaps one another app's vocabulary already
+  claims;
+- declares a term the realm ontology or another app's vocabulary already describes;
+- writes a predicate the platform derives, such as `:isTrusted`;
+- gives your namespace a prefix name Manta already uses, such as `meta:`.
+
+A shapes file is also refused when it declares no `sh:NodeShape`, uses `sh:targetNode`, `sh:targetSubjectsOf` or
+`sh:targetObjectsOf`, or targets a class the realm's own shapes already cover.
+
+`--name` is 1 to 64 lowercase letters, digits and dashes, and may not end in `ontology`, which marks the realm
+ontology. `--namespace` is an http(s) IRI ending in `#` or `/`, and may not overlap a namespace Manta already owns: the
+realm's own vocabulary, an integration's (such as `meta:` or `shopify:`), or RDF, RDFS, OWL, XSD, SHACL and the other
+vocabularies the platform uses.
+
+## Log in
+
+Login works as it does for `manta-codegen` and `manta-upload`: all three register the same commands from
+`@manta-eu/auth`, and share one stored login. Log in once with `manta login`. In CI, set `MANTA_CLIENT_SECRET` for a
+service account token instead.
+
+Writing a vocabulary needs an operator's login, or a custom app's machine token when the app may write data. A token
+a custom app issued to one of its users only reads, so it is refused. A vocabulary a custom app pushes records the app as
+its `dcterms:creator`, and only that app, or an operator, may change or delete it.

package/dist/app-file.d.ts

@@ -0,0 +1,36 @@
+import { type FetchLike, type TokenSource } from "@manta-eu/auth";
+export type AppFilePush = {
+    name: string;
+    graphIri: string;
+    added: number;
+    removed: number;
+    blankNodeTriples: number;
+    changed: boolean;
+    written: boolean;
+    dryRun: boolean;
+};
+export type AppFileDeletion = {
+    name: string;
+    graphIri: string;
+    deleted: boolean;
+};
+export type AppFileCollection = "vocabularies" | "shapes";
+export type AppFileLocation = {
+    apiUrl: string;
+    datastore: string;
+    collection: AppFileCollection;
+    name: string;
+};
+export type AppFileTarget = AppFileLocation & {
+    token: TokenSource;
+    fetchImpl?: FetchLike;
+};
+export declare function appFileEndpoint({ apiUrl, datastore, collection, name }: AppFileLocation): string;
+export declare function pushAppFile(target: AppFileTarget & {
+    namespace?: string;
+    turtle: string;
+    dryRun: boolean;
+}): Promise<AppFilePush>;
+export declare function deleteAppFile(target: AppFileTarget): Promise<AppFileDeletion>;
+export declare function describePush(push: AppFilePush): string;
+//# sourceMappingURL=app-file.d.ts.map

package/dist/app-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-file.d.ts","sourceRoot":"","sources":["../src/app-file.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,SAAS,EAGd,KAAK,WAAW,EAEjB,MAAM,gBAAgB,CAAC;AAExB,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC;AAEnF,MAAM,MAAM,iBAAiB,GAAG,cAAc,GAAG,QAAQ,CAAC;AAE1D,MAAM,MAAM,eAAe,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjH,MAAM,MAAM,aAAa,GAAG,eAAe,GAAG;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,SAAS,CAAC,EAAE,SAAS,CAAA;CAAE,CAAC;AAE5F,wBAAgB,eAAe,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,IAAI,EAAE,EAAE,eAAe,GAAG,MAAM,CAEhG;AAED,wBAAgB,WAAW,CACzB,MAAM,EAAE,aAAa,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAC9E,OAAO,CAAC,WAAW,CAAC,CAUtB;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,eAAe,CAAC,CAE7E;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAStD"}

package/dist/app-file.js

@@ -0,0 +1,50 @@
+import { describeError, readJson, RefusedRequestError, withRenewal, } from "@manta-eu/auth";
+export function appFileEndpoint({ apiUrl, datastore, collection, name }) {
+    return `${apiUrl.replace(/\/$/, "")}/d/${encodeURIComponent(datastore)}/${collection}/${encodeURIComponent(name)}`;
+}
+export function pushAppFile(target) {
+    const endpoint = new URL(appFileEndpoint(target));
+    if (target.namespace !== undefined)
+        endpoint.searchParams.set("namespace", target.namespace);
+    if (target.dryRun)
+        endpoint.searchParams.set("dryRun", "true");
+    return send(target, endpoint.toString(), {
+        method: "PUT",
+        headers: { "content-type": "text/turtle" },
+        body: target.turtle,
+    });
+}
+export function deleteAppFile(target) {
+    return send(target, appFileEndpoint(target), { method: "DELETE", headers: {} });
+}
+export function describePush(push) {
+    const blankNodes = push.blankNodeTriples > 0 ? `, ${push.blankNodeTriples} blank-node triples rewritten` : "";
+    const changes = `${push.added} added, ${push.removed} removed${blankNodes}`;
+    const dryRun = push.dryRun ? " (dry run, nothing written)" : "";
+    if (!push.changed)
+        return `${push.name} is already up to date${dryRun}`;
+    if (push.dryRun)
+        return `${push.name} would change: ${changes}${dryRun}`;
+    return `updated ${push.name} in <${push.graphIri}>: ${changes}`;
+}
+async function send({ token, fetchImpl = fetch }, endpoint, init) {
+    return withRenewal(token, async (accessToken) => {
+        let response;
+        try {
+            response = await fetchImpl(endpoint, {
+                ...init,
+                headers: { ...init.headers, authorization: `Bearer ${accessToken}` },
+            });
+        }
+        catch (cause) {
+            throw new Error(`cannot reach ${endpoint}. ${describeError(cause)}`, { cause });
+        }
+        const body = await readJson(response, endpoint);
+        if (!response.ok) {
+            const reason = typeof body.error === "string" ? `: ${body.error}` : "";
+            throw new RefusedRequestError(`${endpoint} answered status ${response.status}${reason}`, response.status);
+        }
+        return body;
+    });
+}
+//# sourceMappingURL=app-file.js.map

package/dist/app-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-file.js","sourceRoot":"","sources":["../src/app-file.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+import { clientIdHelp, cliTokenSource, defaultDeployment, describeError, registerAuthCommands, } from "@manta-eu/auth";
+import { Command } from "commander";
+import { readFile } from "node:fs/promises";
+import { deleteAppFile, describePush, pushAppFile } from "./app-file.js";
+const label = "manta";
+function withTargetOptions(command) {
+    return command
+        .option("--api-url <url>", "Manta API base URL", defaultDeployment.apiUrl)
+        .requiredOption("--datastore <id>", "datastore to push to")
+        .requiredOption("--name <name>", "your app's name: lowercase letters, digits and dashes")
+        .option("--keycloak-url <url>", "Keycloak base URL", defaultDeployment.keycloakUrl)
+        .option("--keycloak-realm <realm>", "Keycloak realm", defaultDeployment.keycloakRealm)
+        .option("--client-id <id>", clientIdHelp)
+        .option("--scope <scope>", "scope to ask a service account token for")
+        .option("--use-device-code", "if a login is needed, use a one-time code instead of a browser redirect");
+}
+function targetFrom(collection, options) {
+    return {
+        apiUrl: options.apiUrl,
+        datastore: options.datastore,
+        collection,
+        name: options.name,
+        token: cliTokenSource(options, { label }),
+    };
+}
+async function run(action) {
+    try {
+        console.error(`${label}: ${await action()}`);
+    }
+    catch (error) {
+        console.error(`${label}: ${describeError(error)}`);
+        process.exitCode = 1;
+    }
+}
+const program = new Command()
+    .name(label)
+    .description("Keep what a Manta datastore holds in line with files you track in git.");
+function registerAppFileCommands({ command, collection, description, noun, addPushOptions }) {
+    const group = program.command(command).description(description);
+    const push = group
+        .command("push")
+        .description(`make the datastore hold exactly the ${noun} the Turtle file declares`)
+        .argument("<file>", `Turtle file with your app's ${noun}`)
+        .option("--dry-run", "report what would change without writing it");
+    addPushOptions?.(push);
+    withTargetOptions(push).action((file, options) => run(async () => {
+        const turtle = await readFile(file, "utf8");
+        const pushed = await pushAppFile({
+            ...targetFrom(collection, options),
+            namespace: options.namespace,
+            turtle,
+            dryRun: options.dryRun === true,
+        });
+        return describePush(pushed);
+    }));
+    withTargetOptions(group.command("delete").description(`remove your app's ${noun} from the datastore`)).action((options) => run(async () => {
+        const deletion = await deleteAppFile(targetFrom(collection, options));
+        return deletion.deleted ? `deleted ${deletion.name}` : `${deletion.name} was not in the datastore`;
+    }));
+}
+registerAppFileCommands({
+    command: "ontology",
+    collection: "vocabularies",
+    description: "your app's vocabulary: its classes and properties",
+    noun: "vocabulary",
+    addPushOptions: (push) => push.requiredOption("--namespace <iri>", "your app's namespace, ending in # or /: every term the file declares is under it"),
+});
+registerAppFileCommands({
+    command: "shapes",
+    collection: "shapes",
+    description: "your app's SHACL shapes",
+    noun: "shapes",
+});
+registerAuthCommands(program, { label });
+await program.parseAsync();
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { appFileEndpoint, deleteAppFile, describePush, pushAppFile, type AppFileCollection, type AppFileDeletion, type AppFileLocation, type AppFilePush, type AppFileTarget, } from "./app-file.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,aAAa,EACb,YAAY,EACZ,WAAW,EACX,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,aAAa,GACnB,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { appFileEndpoint, deleteAppFile, describePush, pushAppFile, } from "./app-file.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,aAAa,EACb,YAAY,EACZ,WAAW,GAMZ,MAAM,eAAe,CAAC"}

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@manta-eu/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.5.1",
+  "description": "CLI that keeps what a Manta datastore holds in line with files you track in git: your app's vocabulary and shapes",
+  "homepage": "https://developers.manta.eu",
+  "keywords": [
+    "manta",
+    "knowledge-graph",
+    "ontology",
+    "cli"
+  ],
+  "type": "module",
+  "bin": {
+    "manta": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^15.0.0",
+    "@manta-eu/auth": "0.5.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "eslint": "^9.39.2",
+    "rimraf": "^6.1.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.8",
+    "@manta-eu/eslint-config": "0.1.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.*",
+    "!src/**/*.stories.*",
+    "!src/**/__fixtures__",
+    "!src/coverage"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rimraf dist && tsc -p tsconfig.build.json",
+    "test": "vitest --run",
+    "types": "tsc --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  }
 }

package/src/app-file.ts

@@ -0,0 +1,89 @@
+import {
+  describeError,
+  type FetchLike,
+  readJson,
+  RefusedRequestError,
+  type TokenSource,
+  withRenewal,
+} from "@manta-eu/auth";
+
+export type AppFilePush = {
+  name: string;
+  graphIri: string;
+  added: number;
+  removed: number;
+  blankNodeTriples: number;
+  changed: boolean;
+  written: boolean;
+  dryRun: boolean;
+};
+
+export type AppFileDeletion = { name: string; graphIri: string; deleted: boolean };
+
+export type AppFileCollection = "vocabularies" | "shapes";
+
+export type AppFileLocation = { apiUrl: string; datastore: string; collection: AppFileCollection; name: string };
+
+export type AppFileTarget = AppFileLocation & { token: TokenSource; fetchImpl?: FetchLike };
+
+export function appFileEndpoint({ apiUrl, datastore, collection, name }: AppFileLocation): string {
+  return `${apiUrl.replace(/\/$/, "")}/d/${encodeURIComponent(datastore)}/${collection}/${encodeURIComponent(name)}`;
+}
+
+export function pushAppFile(
+  target: AppFileTarget & { namespace?: string; turtle: string; dryRun: boolean },
+): Promise<AppFilePush> {
+  const endpoint = new URL(appFileEndpoint(target));
+  if (target.namespace !== undefined) endpoint.searchParams.set("namespace", target.namespace);
+  if (target.dryRun) endpoint.searchParams.set("dryRun", "true");
+
+  return send<AppFilePush>(target, endpoint.toString(), {
+    method: "PUT",
+    headers: { "content-type": "text/turtle" },
+    body: target.turtle,
+  });
+}
+
+export function deleteAppFile(target: AppFileTarget): Promise<AppFileDeletion> {
+  return send<AppFileDeletion>(target, appFileEndpoint(target), { method: "DELETE", headers: {} });
+}
+
+export function describePush(push: AppFilePush): string {
+  const blankNodes = push.blankNodeTriples > 0 ? `, ${push.blankNodeTriples} blank-node triples rewritten` : "";
+  const changes = `${push.added} added, ${push.removed} removed${blankNodes}`;
+  const dryRun = push.dryRun ? " (dry run, nothing written)" : "";
+
+  if (!push.changed) return `${push.name} is already up to date${dryRun}`;
+  if (push.dryRun) return `${push.name} would change: ${changes}${dryRun}`;
+
+  return `updated ${push.name} in <${push.graphIri}>: ${changes}`;
+}
+
+async function send<T>(
+  { token, fetchImpl = fetch }: AppFileTarget,
+  endpoint: string,
+  init: RequestInit & { headers: Record<string, string> },
+): Promise<T> {
+  return withRenewal(token, async (accessToken) => {
+    let response: Response;
+
+    try {
+      response = await fetchImpl(endpoint, {
+        ...init,
+        headers: { ...init.headers, authorization: `Bearer ${accessToken}` },
+      });
+    } catch (cause) {
+      throw new Error(`cannot reach ${endpoint}. ${describeError(cause)}`, { cause });
+    }
+
+    const body = await readJson<T & { error?: unknown }>(response, endpoint);
+
+    if (!response.ok) {
+      const reason = typeof body.error === "string" ? `: ${body.error}` : "";
+
+      throw new RefusedRequestError(`${endpoint} answered status ${response.status}${reason}`, response.status);
+    }
+
+    return body;
+  });
+}

package/src/cli.ts

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+import {
+  type CliTokenOptions,
+  clientIdHelp,
+  cliTokenSource,
+  defaultDeployment,
+  describeError,
+  registerAuthCommands,
+} from "@manta-eu/auth";
+import { Command } from "commander";
+import { readFile } from "node:fs/promises";
+import { type AppFileCollection, type AppFileTarget, deleteAppFile, describePush, pushAppFile } from "./app-file.js";
+
+const label = "manta";
+
+type TargetOptions = CliTokenOptions & { apiUrl: string; datastore: string; name: string };
+
+function withTargetOptions(command: Command): Command {
+  return command
+    .option("--api-url <url>", "Manta API base URL", defaultDeployment.apiUrl)
+    .requiredOption("--datastore <id>", "datastore to push to")
+    .requiredOption("--name <name>", "your app's name: lowercase letters, digits and dashes")
+    .option("--keycloak-url <url>", "Keycloak base URL", defaultDeployment.keycloakUrl)
+    .option("--keycloak-realm <realm>", "Keycloak realm", defaultDeployment.keycloakRealm)
+    .option("--client-id <id>", clientIdHelp)
+    .option("--scope <scope>", "scope to ask a service account token for")
+    .option("--use-device-code", "if a login is needed, use a one-time code instead of a browser redirect");
+}
+
+function targetFrom(collection: AppFileCollection, options: TargetOptions): AppFileTarget {
+  return {
+    apiUrl: options.apiUrl,
+    datastore: options.datastore,
+    collection,
+    name: options.name,
+    token: cliTokenSource(options, { label }),
+  };
+}
+
+async function run(action: () => Promise<string>): Promise<void> {
+  try {
+    console.error(`${label}: ${await action()}`);
+  } catch (error) {
+    console.error(`${label}: ${describeError(error)}`);
+    process.exitCode = 1;
+  }
+}
+
+const program = new Command()
+  .name(label)
+  .description("Keep what a Manta datastore holds in line with files you track in git.");
+
+type AppFileCommand = {
+  command: string;
+  collection: AppFileCollection;
+  description: string;
+  noun: string;
+  addPushOptions?: (push: Command) => Command;
+};
+
+function registerAppFileCommands({ command, collection, description, noun, addPushOptions }: AppFileCommand): void {
+  const group = program.command(command).description(description);
+  const push = group
+    .command("push")
+    .description(`make the datastore hold exactly the ${noun} the Turtle file declares`)
+    .argument("<file>", `Turtle file with your app's ${noun}`)
+    .option("--dry-run", "report what would change without writing it");
+  addPushOptions?.(push);
+
+  withTargetOptions(push).action((file: string, options: TargetOptions & { namespace?: string; dryRun?: boolean }) =>
+    run(async () => {
+      const turtle = await readFile(file, "utf8");
+      const pushed = await pushAppFile({
+        ...targetFrom(collection, options),
+        namespace: options.namespace,
+        turtle,
+        dryRun: options.dryRun === true,
+      });
+
+      return describePush(pushed);
+    }),
+  );
+
+  withTargetOptions(group.command("delete").description(`remove your app's ${noun} from the datastore`)).action(
+    (options: TargetOptions) =>
+      run(async () => {
+        const deletion = await deleteAppFile(targetFrom(collection, options));
+
+        return deletion.deleted ? `deleted ${deletion.name}` : `${deletion.name} was not in the datastore`;
+      }),
+  );
+}
+
+registerAppFileCommands({
+  command: "ontology",
+  collection: "vocabularies",
+  description: "your app's vocabulary: its classes and properties",
+  noun: "vocabulary",
+  addPushOptions: (push) =>
+    push.requiredOption(
+      "--namespace <iri>",
+      "your app's namespace, ending in # or /: every term the file declares is under it",
+    ),
+});
+
+registerAppFileCommands({
+  command: "shapes",
+  collection: "shapes",
+  description: "your app's SHACL shapes",
+  noun: "shapes",
+});
+
+registerAuthCommands(program, { label });
+
+await program.parseAsync();

package/src/index.ts

@@ -0,0 +1,11 @@
+export {
+  appFileEndpoint,
+  deleteAppFile,
+  describePush,
+  pushAppFile,
+  type AppFileCollection,
+  type AppFileDeletion,
+  type AppFileLocation,
+  type AppFilePush,
+  type AppFileTarget,
+} from "./app-file.js";