References → AppKit CLI
This content applies to Incorta Cloud deployments only.
AppKit is the command-line tool for Incorta Applications. Use it to build applications on your machine with your editor and tools, and push versions back to the platform. It is an alternative to the chat-driven flow in the Incorta UI and works with the same applications and version history.
Prerequisites
- Node.js 22 or later
- Git account
- Bun (for some stacks)
Installation
To install the AppKit tool, run the following command in your terminal:
npm i -g @incorta/appkit
Get help
To get help on the available commands, use the following:
appkit help <command>
Global conventions
You can use the following options with most commands:
--json: Prints machine-readable output. Use it when scripting or driving AppKit from another tool.--yes: On destructive commands, skips the confirmation prompt, and is required when running without a terminal.-hand--help: Displays help for the command
Commands that act on the current application must be run inside a cloned application folder. The create and clone commands create that folder; the rest of the commands operate on it.
Session management
| Command | Purpose | Options |
|---|---|---|
appkit login [url] | Signs you in to an Incorta environment with your browser. You can specify the tenant in the URL (!<tenant_name>) or add the URL without the tenant. Examples: ● appkit login https://mycluster.cloud.incorta/incorta/!mytenant: Opens a new browser tab with the Incorta login page. The tenant will be added automatically, and you cannot change it. ● appkit login https://mycluster.cloud.incorta/incorta: You will be prompted to set the tenant if you haven’t set it before, and then it opens the Incorta login page. ● appkit login: Re-signs you in to the stored environment if a valid session is still available. | ● --tenant <tenant>: The tenant name, when it is not part of the URL ● --client-id <id>: The OAuth client ID the CLI identifies as ● --callback-port <port>: The fixed localhost callback port, for OAuth servers that exactly match the redirect URI ● --timeout <seconds>: How long to wait for browser sign-in (default 300) |
appkit logout | Signs you out and removes the stored session. | |
appkit whoami | Shows the user account used to sign in, the tenant, the API URL, the authentication method, and the access token expiration time. | |
appkit doctor | Checks whether the CLI is set up and can reach the platform, including Node.js, Git, configurations, login, and API connectivity. Run this command first when nothing is working. |
Application management
| Command | Purpose | Options |
|---|---|---|
appkit apps list | Lists the applications you have access to. | |
appkit create | Creates a new application on the platform and clones its workspace into a local folder. | ● --name <name>: Application name ● --description <text>: Application description ● --stack <stack>: The framework used to build the app (omit for the platform default) ● --dir <folder>: The target folder (default: derived from the name) Example: appkit create --name "My App" --description "One sentence" --dir my-app |
appkit clone <app> | Clones an existing application, by ID or name, into a linked local folder. | --dir <folder>: The target folder (default: derived from the name) |
Build and run locally
| Command | Purpose | Options |
|---|---|---|
appkit dev | Runs the application's dev server locally, signed in as you, against live Incorta data. | --json: Prints the machine-readable startup descriptor |
appkit env pull | Writes the application's secrets and Incorta development credentials into .env for local runs. .env is platform-managed; users should not hand-edit it. |
Versions and syncing
| Command | Purpose | Options |
|---|---|---|
appkit push | Pushes local commits to the application workspace. Each push creates a version. | ● --commit: Commits all local changes first ● -m <message> or --message <message>: Adds a message when using the --commit command |
appkit deploy | Pushes local commits and builds a shareable preview. | ● --commit: Commits all local changes first ● -m <message> or --message <message>: Adds a message when using the --commit command |
appkit pull | Fetches new workspace commits and fast-forwards the local repository. Use it after someone else, or the agent in the UI, has changed the application. | |
appkit status | Shows local versus workspace drift, versions, and run activity. | |
appkit versions | Lists versions with build status, and which is current and which is live. | |
appkit revert <version> | Restores the workspace to an older version and syncs locally. | --yes: Skips the confirmation (required when headless) |
Publishing
| Command | Purpose | Options |
|---|---|---|
appkit publish | Makes a deployed version live on its stable subdomain. | ● --version <n>: Publishes a specific version instead of the current one (rollback) ● --subdomain <name>: The address to serve at (first publish) ● --confirm <runId>: Reviews and confirms a publish run parked for confirmation ● --accept-data-loss: (Headless) Acknowledges every destructive schema change ● --accept-advisories: (Headless) Acknowledges every dependency advisory ● --accept-advisories: (Headless) Acknowledges every dependency advisory ● --accept-code-findings: (Headless) Acknowledges every code-analysis finding ● --show-sql or --verbose: Prints the exact SQL the run will execute ● --no-wait: Completes the publish process in the background once the run is confirmed, allowing for running more commands. |
appkit unpublish | Take the published application offline. | --yes: Skips the confirmation (required when headless) |
appkit open | Open the application in the browser. | ● --live: The published address ● --preview: The current version's preview ● --platform: The application page in the Incorta Apps web UI |
The --accept-data-loss, --accept-advisories, and --accept-code-findings flags tell appkit publish to continue without stopping for your review. Normally, a publish pauses so that you can check database changes that delete data and security findings in your application. With these flags, the publish process skips those checks and goes ahead automatically, which can permanently delete production data or publish an application with known security issues.
Use these flags only in unattended automated pipelines, such as CI/CD, and only after you have reviewed what the publish process will change. To preview the database changes first, run appkit publish --show-sql.
Database
| Command | Purpose |
|---|---|
appkit db push | Applies db/schema.ts and refreshes generated files. |
appkit db types | Regenerates language bindings without changing the database. |
Secrets
The secret commands apply to the development secrets by default unless you use the --production option.
| Command | Purpose | Options |
|---|---|---|
appkit secrets list | Lists secret names and timestamps. Values are never shown. | --production: Lists the secrets of the published application instead of the development’s set |
appkit secrets set [entries...] | Creates or updates one or more secrets. Enter each secret as a NAME=value pair. To enter a secret value at a prompt instead, enter only the secret name (NAME). | ● --file <path>: Imports all secrets from a dotenv (.env) file ● --stdin: Reads the secret value from standard input, so the value is not saved in your shell history or visible in the process list ● --production: Updates the production secrets that the published application uses. The published application restarts to apply the change. ● --no-apply: Use this option with --production to save the change without restarting the published application. The change takes effect when you run appkit secrets apply. |
appkit secrets rm <names...> | Removes secrets by name. | ● --production: Removes secrets from the published set, resulting in restarting the published application immediately. ● --yes: Skips the confirmation |
appkit secrets apply | Applies saved production secrets and restarts the published application. | --restart: Restarts even when nothing is changed. |
appkit secrets add-to-production [names...] | Copies development secrets into the production set. | ● --all: Copies every development secret that is not available in the production’s set ● --no-apply: Saves the change without restarting the published application. The change takes effect when you run appkit secrets apply. |
To keep secret values secure, use --stdin or the prompt instead of entering values directly in the command.
Logs
By default, applications write very little to the logs. You might see only the line that shows the application started. To see more detail, ask the Builder Agent to add logging to the parts of the application you want to monitor.
| Command | Purpose | Options |
|---|---|---|
appkit logs | Shows the application's recent output. | ● -f, --follow: Keeps showing new log entries as they arrive, until you stop the command (for example, with Ctrl+C) ● --source <source>: Shows logs from one source only: dev for the dev server preview for previews and the published application ● --version <n>: Shows logs from the preview or published application of version n only ● --stream <stream>: Shows one output stream only: stdout for standard output or stderr for errors. Markers that indicate missing log entries always appear. ● -n or --limit <count>: The number of most recent log entries to show, from 1 to 500. The default is 100. ● --json: Shows each log entry as a JSON object on its own line (NDJSON) |