DeSciX CLI

The official command-line interface for the DeSciX platform.

Installation

npm install -g @descix/cli

Quick Start

1. Login to DeSciX:

   descix login

2. Initialize your workspace:

   descix init

   This writes .descix/workspace.json for the current project. Pass -c <community_id> -a <app_id> to pre-fill the app context, or --from-invite <token> to resolve an invite token.

   Choosing an environment: The --dev flag has been REMOVED. Its absence silently meant production, so the most common invocation targeted PROD without saying so. Name the environment instead:

   descix config init --env dev      # or demo, or prod

   An unconfigured workspace resolves to the declared default, PROD, and every network-bound command prints the environment, origin and source it resolved on stderr. For a local backend, name the URL: per run descix --api-url https://localhost:4000 <command>, or persistently descix config set-env local --url https://localhost:4000 (set-env refuses a known name).

3. Check your status:

   descix status

Workspace Modes

The CLI supports three workspace modes to accommodate different development needs:

1. Single App Mode (single_app)

Best for individual developers working on one app.

• Structure: The root folder is your app folder.
• Drive Path: {community_id}/{app_id}/

2. Single Community Mode (single_community)

Best for teams managing multiple apps within one community.

• Structure: The root folder is the community folder, containing subfolders for each app.
• Drive Path: {community_id}/

3. Multi-Community Mode (multi_community)

Best for platform admins or agencies managing multiple communities.

• Structure: The root folder contains subfolders for each community.
• Drive Path: / (Root of your base folder)

Core Commands

• descix login: Authenticate with the platform.
• descix status: View your current environment status and workspace mode.
• descix init: Initialize workspace for DeSciX app development (Git-aware) — writes .descix/workspace.json.
• descix app init: Create (when it does not exist yet) and initialize an app — the one path to an app. See Creating an App.
• descix site init / descix site upload: Scaffold an app's site, then build and deploy it. See Deploying a Site.
• descix app sync-assets: Sync local assets (system_instructions.md, app_description.md, icon.png) to the platform.
• descix drive pull / descix drive push: Drive content authoring — pull from Drive to local markdown, push staging back to Drive.
• descix kb: Manage Knowledge Bases (list, create, delete, and corpus sync).

Knowledge Base Management (Git Mode)

The CLI exposes exactly ONE knowledge-base sync surface: descix kb corpus sync, driven by a git-tracked corpus manifest. The older four-step local pipeline has been REMOVED — its invocations now exit non-zero and name this replacement.

1. Create the knowledge base (once per KB; an app created by descix app init already has its default KB):

   descix kb create -a <app_id> --kb <kb_name>

2. Author a corpus manifest at .descix/manifests/<kb_name>.json describing the sources to sync.
3. Sync the corpus to the platform (Pinecone):

   descix kb corpus sync -a <app_id> [-k <kb_name>]

   It walks the git blobs at the manifest's ref, so only changed files are re-vectorized. Useful flags: --dry-run (report drift, write nothing), --show-walk (print the resolved ref and the files it would walk), --ref <ref> (override the git ref for all manifest sources).

From a gateway workspace, -a <appId> on kb corpus sync, kb corpus status and kb doctor names the listed repo (env.gateway.shell or env.gateway.appRepos[]) whose own workspace holds that app: its .descix/manifests/<kb_name>.json, its git tree (walked at the manifest ref), its sync-state and its env.app.communityId are used, while the env, origin and sign-in stay the gateway's. An appId no listed repo holds is refused, naming the repos searched and the remedies (descix config gateway add-repo <repo>, or run from the app's repo root); there is no -p form, the manifest is required. Every run prints App repo: first.

To fetch source documents from Google Drive into local markdown, use descix drive pull.

Creating an App

descix app init is the one path to an app. It creates the app on the platform when it does not exist yet, then registers and scaffolds it locally — one command, not two.

descix app init -a <name> -c <community>

Pass -c to create a new app in that community. Omit -c to initialize an app that already exists — the CLI resolves the app from the Products registry and only does the local half.

The command is idempotent, so re-running it on a half-made app finishes the job.

Options:

• -a, --app <app_id> (required): the app ID. With -c, this is the app NAME to create.
• -c, --community <id>: the community to create the app in. It must already be materialized in this environment. Required only for creation.
• -s, --short <short_name>: the short id segment (no hyphens). The app_id is composed server-side as {community}-{short}; defaults to --app.
• --overwrite: when creating, overwrite an existing app record intentionally.
• --kb <name>: knowledge base name (default: General).

What it does, in order:

1. Creates the app (only when -c is given and the app does not exist): the server composes the unique app_id and writes Products/{app_id} and Community/{community}/Apps/{app_id}. Every app is guaranteed a default knowledge base at creation.
2. Writes it as env.app in .descix/workspace.json — the current directory, the repo root, becomes the workspace root. A workspace holds one app: a repo that already holds a different app is refused, and so is a directory nested inside another DeSciX workspace.
3. Scaffolds the app folder: creates site/, microservice/ and assets/, and writes assets/system_instructions.md and assets/app_description.md when they do not exist.
4. Creates the knowledge base record for Git-mode sync.

It fails loud rather than guessing: initializing an app that does not exist without -c names the -c invocation that would create it; a -c that disagrees with the app's real community is refused.

Next step — author a corpus manifest at .descix/manifests/<kb_name>.json, then descix kb corpus sync -a <app_id>.

Creating a community is a separate, admin-only operation: descix community create requires platform-admin membership and deploys a real ERC-20 token contract to live Polygon. App developers work inside a community that already exists.

Deploying a Site

An app's site is scaffolded, then uploaded. descix site upload is the deploy verb — there is no descix site deploy.

descix site init      # scaffold site/ (optional — upload works on any site directory)
descix site upload --env dev

descix site init

Copies the site scaffold — index.html, app.js, styles.css, DeSciXAppSDK.js, README.md — into the app's site/ directory. The workspace must already hold the app (env.app, written by descix app init).

• -f, --force: overwrite an existing site/ folder.
• -c, --community <id> / -a, --app <id>: auto-detected from context when omitted.

It scaffolds site content only; it writes no manifest. Skip it entirely if you already have a site.

descix site upload

Builds (when a manifest declares a build) and uploads the site to GCS, then updates the app's metadata. Files are uploaded straight to GCS with short-lived signed URLs issued by get_site_deploy_token; confirm_site_deploy then records the deploy and returns the site URL.

After a non-preview deploy the server purges the edge cache for the files the deploy made stale and returns a receipt, printed as one line: edge purge: ok, 33/33 cache keys (each stale path is purged once plain and once per page origin, so the count is cache keys, not files). When the purge is not complete (status not ok, or fewer keys purged than attempted), or the confirm carries no receipt, the command prints the receipt and the failed batches and exits non-zero: the deploy is confirmed, but the edge may serve stale copies until their cache TTL. Re-running the same descix site upload re-purges every file. A preview deploy is not purged (edge purge: not run (preview deploy)).

• -p, --path <localPath>: directory to deploy (default ./site). Ignored when a site manifest exists.
• --preview: deploy to the preview path.
• --dry-run: show what would be deployed.
• --no-cache: set Cache-Control: no-cache.
• -c, --community <id> / -a, --app <id>: auto-detected from context when omitted.

From a gateway workspace, -a <appId> names the listed repo (env.gateway.shell or env.gateway.appRepos[]) whose own workspace holds that app; its manifest, build and sources are read there, while the env, origin and sign-in stay the gateway's; an explicit -p is then ignored and the run says so. For an appId no listed repo holds, an explicit -p <built dist> uploads that directory for the app under the gateway's sign-in (App repo: none listed; uploading --path <dir> for app <appId>); without one the upload is refused, naming the repos searched and the three remedies (add-repo, run from the app's repo, or -p). The ./site default never counts as a -p in a gateway workspace. Every run prints App repo: (and, for a listed repo, Site manifest:) first.

Site deploys target a cloud environment. An upload that resolves to a local backend without this invocation naming its target is refused — pass --env <dev|demo|prod>.

Manifest-driven builds. When {app_root}/.descix/manifests/site.json exists it takes over from -p. Author it yourself; nothing generates it for you. It declares the sources to walk and, optionally, a buildCommand, which runs in the app root with the environment-specific VITE_* build variables the server returns injected into its environment:

{
  "sources": [{ "path": "site/dist", "include": ["**/*"] }],
  "buildCommand": "npm run build --prefix site"
}

Documentation

For full documentation, please refer to the DeSciX SDK Documentation.