Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Login
✓ npx instant-cli@latest login
✗ instant-cli login
Always prefer `npx` for zero-install execution. If globally installed, `instant-cli login` works. The `@latest` ensures the most recent version is used.
Init
✓ npx instant-cli@latest init
✗ npx instant-cli@latest create-app
The `init` command guides through creating schema/perms files. `create-app` is an older, likely deprecated, command or refers to an external tool (`create-instant-app`).
PushSchema
✓ npx instant-cli@latest push schema
✗ npx instant-cli push
Explicitly specify `schema` to push your data model changes. Without it, the command might fail or not perform the intended action.
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."
instant --version
Debug
Known issues
gotchaWhen 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.fixFor 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.
affects: >=1.0.0
breakingThe `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.fixUpdate 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.
affects: >=1.0.0 (based on documentation changes)
gotchaFor 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.fixRun `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.
affects: >=1.0.0
gotchaQueries 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.fixOptimize 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.
affects: >=1.0.0
Errors
Common errors & fixes
unknown command 'create-app'
The `create-app` command is deprecated or has been replaced by `init` or `create-instant-app`.
fixUse `npx instant-cli@latest init` to initialize a new project, or `npx create-instant-app` to scaffold a new application.
Error: Command failed with exit code 1: instant-cli login
The `instant-cli` package is not globally installed or `npx` cannot resolve it, or there was an issue during the interactive login process.
fixEnsure 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`.
INVALID DATA adding required constraint to <entity>.<attribute>
Attempting to make an optional attribute required in `instant.schema.ts` when existing entities in the database have `null` values for that attribute.
fixBefore 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.
Permission denied: not perms-pass?
The current user or authentication token lacks the necessary permissions defined in `instant.perms.ts` to perform the requested operation.
fixReview 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.
Audit
Dependencies
@commander-js/extra-typingsrequiredCommand-line parsing and argument handling.
@instantdb/corerequiredCore InstantDB functionalities and data model definitions.
commanderrequiredRobust command-line interfaces.
dotenvrequiredLoading environment variables from .env files.
typescriptrequiredUsed for schema and permissions file generation and type-checking, as InstantDB encourages a TypeScript-first approach.
openrequiredOpening browser windows for interactive login flows.