From cc67cf55dd624064575985339ab092bb993dc9bf Mon Sep 17 00:00:00 2001 From: Joe Averbukh Date: Fri, 20 Mar 2026 13:56:33 -0700 Subject: [PATCH 1/4] [Docs] Add docs for cli query --- client/www/pages/docs/cli.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/client/www/pages/docs/cli.md b/client/www/pages/docs/cli.md index 1a8c7e1bf7..ab5ccafb16 100644 --- a/client/www/pages/docs/cli.md +++ b/client/www/pages/docs/cli.md @@ -98,6 +98,30 @@ npx instant-cli@latest pull This will generate new `instant.schema.ts` and `instant.perms.ts` files, based on your production state. +## Query + +You can run InstaQL queries against your app directly from the terminal: + +```shell {% showCopy=true %} +npx instant-cli@latest query --admin '{ posts: { comments: {} } }' +``` + +This outputs clean JSON to stdout, making it easy to pipe into `jq` or use in scripts. It supports JSON5 syntax, so you don't need to quote your keys. + +Each query requires an auth context flag: + +- `--admin` bypasses permissions entirely +- `--as-email ` runs the query as a specific user with permissions applied +- `--as-guest` runs the query as an unauthenticated guest + +For example, to see what a specific user can access: + +```shell {% showCopy=true %} +npx instant-cli@latest query --as-email alice@example.com '{ posts: {} }' +``` + +The results match what your client queries return, including cardinality. If your schema defines a relationship as `has: "one"`, you'll get back a single object instead of an array. + ## App ID Whenever you run a CLI command, we look up your app id. You can either provide an app id as an option: From 14eaf6946f41bdaded12da004b483a7991da5829 Mon Sep 17 00:00:00 2001 From: Joe Averbukh Date: Fri, 20 Mar 2026 14:01:05 -0700 Subject: [PATCH 2/4] sm --- client/www/pages/docs/cli.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/client/www/pages/docs/cli.md b/client/www/pages/docs/cli.md index ab5ccafb16..706cd04019 100644 --- a/client/www/pages/docs/cli.md +++ b/client/www/pages/docs/cli.md @@ -103,14 +103,14 @@ This will generate new `instant.schema.ts` and `instant.perms.ts` files, based o You can run InstaQL queries against your app directly from the terminal: ```shell {% showCopy=true %} -npx instant-cli@latest query --admin '{ posts: { comments: {} } }' +npx instant-cli@latest query '{ posts: { comments: {} } }' ``` This outputs clean JSON to stdout, making it easy to pipe into `jq` or use in scripts. It supports JSON5 syntax, so you don't need to quote your keys. Each query requires an auth context flag: -- `--admin` bypasses permissions entirely +- `--admin` bypasses permissions (default) - `--as-email ` runs the query as a specific user with permissions applied - `--as-guest` runs the query as an unauthenticated guest From 993dbe71b06beed1b039d8b2877c7c403f26eca9 Mon Sep 17 00:00:00 2001 From: Joe Averbukh Date: Fri, 20 Mar 2026 14:12:57 -0700 Subject: [PATCH 3/4] [CLI] Use admin context by default for instant-cli query --- .../cli/__tests__/e2e/cli.e2e.test.ts | 27 +++++++++++++++---- client/packages/cli/src/index.js | 6 ----- 2 files changed, 22 insertions(+), 11 deletions(-) diff --git a/client/packages/cli/__tests__/e2e/cli.e2e.test.ts b/client/packages/cli/__tests__/e2e/cli.e2e.test.ts index 1454c894eb..5bb31d2f53 100644 --- a/client/packages/cli/__tests__/e2e/cli.e2e.test.ts +++ b/client/packages/cli/__tests__/e2e/cli.e2e.test.ts @@ -700,11 +700,27 @@ export default _schema; } }); - it('fails without context flag', async () => { + it('defaults to admin context when no context flag is provided', async () => { const { appId, adminToken } = await createTempApp(); - const project = await createTestProject({ appId }); + const project = await createTestProject({ + appId, + schemaFile: SCHEMA_FILE, + }); try { + const pushResult = await runCli(['push', 'schema', '--yes'], { + cwd: project.dir, + env: { + INSTANT_CLI_AUTH_TOKEN: adminToken, + INSTANT_APP_ID: appId, + }, + }); + expect(pushResult.exitCode).toBe(0); + + await adminTransact(appId, adminToken, [ + ['update', 'posts', randomUUID(), { title: 'Hello', body: 'World' }], + ]); + const result = await runCli(['query', JSON.stringify({ posts: {} })], { cwd: project.dir, env: { @@ -713,9 +729,10 @@ export default _schema; }, }); - expect(result.exitCode).not.toBe(0); - const output = result.stdout + result.stderr; - expect(output).toMatch(/--admin|--as-email|--as-guest/); + expect(result.exitCode).toBe(0); + const data = JSON.parse(result.stdout); + expect(data.posts).toHaveLength(1); + expect(data.posts[0].title).toBe('Hello'); } finally { await project.cleanup(); } diff --git a/client/packages/cli/src/index.js b/client/packages/cli/src/index.js index 5ea0f76e8f..8031fc40a4 100644 --- a/client/packages/cli/src/index.js +++ b/client/packages/cli/src/index.js @@ -718,12 +718,6 @@ async function detectAppIdQuietly(opts) { async function handleQuery(queryArg, opts) { const contextCount = (opts.admin ? 1 : 0) + (opts.asEmail ? 1 : 0) + (opts.asGuest ? 1 : 0); - if (contextCount === 0) { - error( - 'Please specify a context: --admin, --as-email , or --as-guest', - ); - return process.exit(1); - } if (contextCount > 1) { error( 'Please specify exactly one context: --admin, --as-email , or --as-guest', From 38646c72fe510d47bedef5b28e984218ef515b08 Mon Sep 17 00:00:00 2001 From: Joe Averbukh Date: Fri, 20 Mar 2026 14:13:30 -0700 Subject: [PATCH 4/4] bump v0.22.167 --- client/packages/version/src/version.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/client/packages/version/src/version.ts b/client/packages/version/src/version.ts index 7314b12c11..b917f15cc6 100644 --- a/client/packages/version/src/version.ts +++ b/client/packages/version/src/version.ts @@ -2,6 +2,6 @@ // Update the version here and merge your code to main to // publish a new version of all of the packages to npm. -const version = 'v0.22.166'; +const version = 'v0.22.167'; export { version };