{"id":17716,"library":"instant-cli","title":"Instant CLI","description":"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.","status":"active","version":"1.0.14","language":"javascript","source_language":"en","source_url":"https://github.com/instantdb/instant","tags":["javascript"],"install":[{"cmd":"npm install instant-cli","lang":"bash","label":"npm"},{"cmd":"yarn add instant-cli","lang":"bash","label":"yarn"},{"cmd":"pnpm add instant-cli","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Command-line parsing and argument handling.","package":"@commander-js/extra-typings"},{"reason":"Core InstantDB functionalities and data model definitions.","package":"@instantdb/core"},{"reason":"Robust command-line interfaces.","package":"commander"},{"reason":"Loading environment variables from .env files.","package":"dotenv"},{"reason":"Used for schema and permissions file generation and type-checking, as InstantDB encourages a TypeScript-first approach.","package":"typescript"},{"reason":"Opening browser windows for interactive login flows.","package":"open"}],"imports":[{"note":"Always prefer `npx` for zero-install execution. If globally installed, `instant-cli login` works. The `@latest` ensures the most recent version is used.","wrong":"instant-cli login","symbol":"Login","correct":"npx instant-cli@latest login"},{"note":"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`).","wrong":"npx instant-cli@latest create-app","symbol":"Init","correct":"npx instant-cli@latest init"},{"note":"Explicitly specify `schema` to push your data model changes. Without it, the command might fail or not perform the intended action.","wrong":"npx instant-cli push","symbol":"PushSchema","correct":"npx instant-cli@latest push schema"}],"quickstart":{"code":"#!/bin/bash\n\n# Ensure npx is available\nif ! command -v npx &> /dev/null\nthen\n    echo \"npx not found. Please install Node.js and npm/npx.\" >&2\n    exit 1\nfi\n\necho \"Logging into InstantDB... A browser window will open for authentication.\"\nnpx instant-cli@latest login\n\necho \"Initializing a new InstantDB project...\"\n# This will prompt you to select an app and generate instant.schema.ts and instant.perms.ts\nnpx instant-cli@latest init\n\n# Example: Create a simple schema file (instant.schema.ts)\necho '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\n\necho \"Pushing schema changes to InstantDB...\"\nnpx instant-cli@latest push schema\n\necho \"Done! Your InstantDB project is set up and schema pushed. You can now use `npx instant-cli@latest --help` for more commands.\"\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0 (based on documentation changes)"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Use `npx instant-cli@latest init` to initialize a new project, or `npx create-instant-app` to scaffold a new application.","cause":"The `create-app` command is deprecated or has been replaced by `init` or `create-instant-app`.","error":"unknown command 'create-app'"},{"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`.","cause":"The `instant-cli` package is not globally installed or `npx` cannot resolve it, or there was an issue during the interactive login process.","error":"Error: Command failed with exit code 1: instant-cli login"},{"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.","cause":"Attempting to make an optional attribute required in `instant.schema.ts` when existing entities in the database have `null` values for that attribute.","error":"INVALID DATA adding required constraint to <entity>.<attribute>"},{"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.","cause":"The current user or authentication token lacks the necessary permissions defined in `instant.perms.ts` to perform the requested operation.","error":"Permission denied: not perms-pass?"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}