The Instant CLI was designed to drive your Instant application entirely from a project's codebase. You can create apps as well as define an app's schema and permission rules all from the terminal.

The CLI is currently optimized for starting new projects that are managed entirely from code. See the migration guide below if you have an existing app.

npm install -D instant-cli

You can view all commands and flags with npx instant-cli -h.

Configuration as code

Instant CLI relies on the presence of two core config files: instant.schema.ts, where you define your application's graph structure, and instant.perms.ts, where you define access control rules for all of your graph's constructs.

You can learn more about schemas here here and permissions here.

Actions

Logging in

The first step to using the CLI is to log in with your Instant account.

npx instant-cli login

Note, this command will open Instant's dashboard in a browser window and prompt you to log in.

Initializing a project

Similar to git init, running instant-cli init will generate a new app id and add instant.schema.ts and instant.perms.ts files if none are present in your current directory.

npx instant-cli init

instant-cli init will spin up a new app under your account. It will also add instant.schema.ts and instant.perms.ts files if none are present in your project.

Push schema

npx instant-cli push-schema

push-schema evals your instant.schema.ts file and applies it your app's production database. Read more about schema as code.

Note, to avoid accidental data loss, push-schema does not delete entities or fields you've removed from your schema. You can manually delete them in the Explorer.

Here's an example instant.schema.ts file.

import { i } from '@instantdb/core';

const INSTANT_APP_ID = 'YOUR_APP_ID_HERE';

const graph = i.graph(
  INSTANT_APP_ID,
  {
    authors: i.entity({
      userId: i.string(),
      name: i.string(),
    }),
    posts: i.entity({
      name: i.string(),
      content: i.string(),
    }),
  },
  {
    authorPosts: {
      forward: {
        on: 'authors',
        has: 'many',
        label: 'posts',
      },
      reverse: {
        on: 'posts',
        has: 'one',
        label: 'author',
      },
    },
  }
);

export default graph;

Push perms

npx instant-cli push-perms

push-perms evals your instant.perms.ts file and applies it your app's production database. instant.perms.ts should export an object implementing Instant's standard permissions CEL+JSON format. Read more about permissions in Instant.

Here's an example instant.perms.ts file.

export default {
  allow: {
    posts: {
      bind: ['isAuthor', "auth.id in data.ref('authors.userId')"],
      allow: {
        view: 'true',
        create: 'isAuthor',
        update: 'isAuthor',
        delete: 'isAuthor',
      },
    },
  },
};

Pull: migrating from the dashboard

If you already created an app in the dashboard and created some schema and permissions, you can run npx instant-cli pull <APP_ID> to generate an instant.schema.ts and instant.perms.ts files based on your production configuration.

npx instant-cli pull-schema <APP_ID>
npx instant-cli pull-perms [APP_ID] # ID optional if there's already an instant.schema.ts
npx instant-cli pull <APP_ID> # pulls both schema and perms