Platform features
Instant CLI
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
Note: Strongly typed attributes are under active development. For now, pull-schema
will default all attribute types to i.any()
.