Instant CLI

raw JSON →
1.0.14 verified Thu Apr 23 auth: no javascript

The Instant CLI is a command-line interface tool designed to manage applications built with InstantDB, a real-time, schema-defined backend-as-a-service. It enables developers to perform various operations directly from the terminal, including authenticating with their Instant account, initializing new Instant applications, defining and evolving data models via `instant.schema.ts` files, and managing permissions through `instant.perms.ts` files. The CLI is actively maintained, with frequent updates, and currently stable at version 1.0.14. Key differentiators include its tight integration with the InstantDB platform, support for LLM agents to programmatically interact with the backend, and features for both local development and CI/CD pipelines, emphasizing a code-first approach to backend management.

Common errors

error unknown command 'create-app' ↓
cause The `create-app` command is deprecated or has been replaced by `init` or `create-instant-app`.
fix
Use npx instant-cli@latest init to initialize a new project, or npx create-instant-app to scaffold a new application.
error Error: Command failed with exit code 1: instant-cli login ↓
cause The `instant-cli` package is not globally installed or `npx` cannot resolve it, or there was an issue during the interactive login process.
fix
Ensure Node.js and npm/npx are installed. Always prefix commands with npx instant-cli@latest for reliable execution. If using a global install, run npm install -g instant-cli.
error INVALID DATA adding required constraint to <entity>.<attribute> ↓
cause Attempting to make an optional attribute required in `instant.schema.ts` when existing entities in the database have `null` values for that attribute.
fix
Before pushing schema changes that make an attribute required, ensure all existing records for that entity have non-null values for the affected attribute. This may require a data migration or backfilling of default values.
error Permission denied: not perms-pass? ↓
cause The current user or authentication token lacks the necessary permissions defined in `instant.perms.ts` to perform the requested operation.
fix
Review your instant.perms.ts file to ensure the correct permission rules are in place for the user/token. Use npx instant-cli@latest login -p to get a token with appropriate permissions, or use --admin flag for administrative operations in development contexts.

Warnings

gotcha When renaming an attribute or link in your `instant.schema.ts` and performing a `push` operation, the CLI will interactively prompt you to confirm if it's a rename or a delete/create operation. This can halt automated CI/CD pipelines. ↓
fix For automated environments, consider using `instant-cli` commands that support non-interactive flags if available, or carefully manage schema migrations to avoid ambiguity where interactive prompts would occur. Consult the InstantDB documentation for specific non-interactive schema migration strategies.
breaking The `create-app` command, previously mentioned in some documentation, is no longer directly available as `npx instant-cli create-app`. Project creation is now handled either by `npx instant-cli init` or the external `npx create-instant-app` utility. ↓
fix Update scripts and workflows to use `npx instant-cli@latest init` for initial project setup and schema/permissions file generation, or `npx create-instant-app` for scaffolding full projects with templates.
gotcha For continuous integration (CI) environments, interactive login is not feasible. Authentication requires providing an `INSTANT_CLI_AUTH_TOKEN` environment variable, which needs to be obtained through a specific non-interactive login flow. ↓
fix Run `npx instant-cli@latest login -p` in a controlled environment to print an authentication token to the console. Store this token securely as an `INSTANT_CLI_AUTH_TOKEN` environment variable in your CI/CD setup.
gotcha Queries and transactions executed through InstantDB, whether via the CLI or SDKs, have inherent timeout limits (e.g., 5 seconds for client SDK, 30 seconds for admin SDK/sandbox). Exceeding these limits results in timeout errors, impacting application performance and reliability. ↓
fix Optimize queries by adding indexes, using pagination, or fetching less data. Break down large transactions into smaller, more manageable operations. Utilize the InstantDB dashboard's Sandbox to debug query and transaction performance.

Install

npm install instant-cli
yarn add instant-cli
pnpm add instant-cli

Imports

Quickstart

This quickstart logs into InstantDB, initializes a new project (creating `instant.schema.ts` and `instant.perms.ts`), populates a basic todo schema, and then pushes it to the InstantDB backend.

#!/bin/bash

# Ensure npx is available
if ! command -v npx &> /dev/null
then
    echo "npx not found. Please install Node.js and npm/npx." >&2
    exit 1
fi

echo "Logging into InstantDB... A browser window will open for authentication."
npx instant-cli@latest login

echo "Initializing a new InstantDB project..."
# This will prompt you to select an app and generate instant.schema.ts and instant.perms.ts
npx instant-cli@latest init

# Example: Create a simple schema file (instant.schema.ts)
echo 'import { i } from "@instantdb/react";\n\nconst schema = i.schema({\n  entities: {\n    todos: i.entity({\n      text: i.string(),\n      done: i.boolean().default(false),\n      createdAt: i.number().default(() => Date.now()),\n    }),\n  },\n});\n\nexport default schema;\n' > instant.schema.ts

echo "Pushing schema changes to InstantDB..."
npx instant-cli@latest push schema

echo "Done! Your InstantDB project is set up and schema pushed. You can now use `npx instant-cli@latest --help` for more commands."
last verified Thu Apr 23
next check Wed Jul 22