fix: allow commands to run outside project context with --project-id/--dataset flags (#558)

Author: rexxars

Claude.md

@@ -195,7 +195,7 @@ test('with mockApi', async () => {
 
   const {error, stdout} = await testCommand(MyCommand, [])
 
-  expect(error).toBeUndefined()
+  if (error) throw error
   expect(stdout).toContain('project-123')
 })
 ```
@@ -244,6 +244,8 @@ When writing tests for CLI commands, follow these rules strictly:
 3. **Use hoisted mocks** - Use `vi.hoisted(() => vi.fn())` for client method mocks
 4. **Clear mocks in afterEach** - Always include `vi.clearAllMocks()` in `afterEach()`
 5. **Test error cases** - Include both success and error scenarios
+6. **Use `if (error) throw error`** in success tests - NOT `expect(error).toBeUndefined()`. This gives better stack traces on failure.
+7. **Assert `expect(error).toBeInstanceOf(Error)`** in error tests - along with exit code and message assertions
 
 #### NEVER:
 

packages/@sanity/cli-core/src/SanityCommand.ts

@@ -212,4 +212,21 @@ export abstract class SanityCommand<T extends typeof Command> extends Command {
   protected resolveIsInteractive(): boolean {
     return isInteractive()
   }
+
+  /**
+   * Get the CLI config, returning an empty config if no project root is found.
+   *
+   * Use this instead of `getCliConfig()` in commands that can operate without a
+   * project directory (e.g. when `--project-id` and `--dataset` flags are provided).
+   *
+   * @returns The CLI config, or an empty config object if no project root is found.
+   */
+  protected async tryGetCliConfig(): Promise<CliConfig> {
+    try {
+      return await this.getCliConfig()
+    } catch (err) {
+      if (!(err instanceof ProjectRootNotFoundError)) throw err
+      return {}
+    }
+  }
 }

packages/@sanity/cli-test/src/test/mockSanityCommand.ts

@@ -91,6 +91,13 @@ export function mockSanityCommand<T extends typeof SanityCommand<typeof Command>
     }
 
     protected getProjectRoot(): Promise<ProjectRootResult> {
+      if (
+        options.cliConfigError &&
+        'name' in options.cliConfigError &&
+        options.cliConfigError.name === 'ProjectRootNotFoundError'
+      ) {
+        return Promise.reject(options.cliConfigError)
+      }
       if (options.projectRoot) {
         return Promise.resolve(options.projectRoot)
       }

packages/@sanity/cli/src/commands/dataset/__tests__/export.test.ts

@@ -293,6 +293,50 @@ describe('#dataset:export', () => {
       expect(mockExportDataset).toHaveBeenCalledWith(expect.objectContaining({dataset: 'staging'}))
     })
 
+    test('exports with --project-id flag and dataset arg when outside project directory', async () => {
+      mockGetProjectCliClient.mockResolvedValue({
+        datasets: {
+          list: vi.fn().mockResolvedValue([{name: 'production'}]),
+        },
+      } as never)
+      mockFs.stat.mockRejectedValue(new Error('File not found'))
+
+      const {error, stdout} = await testCommand(
+        DatasetExportCommand,
+        ['production', 'output.tar.gz', '--project-id', 'flag-project'],
+        {
+          mocks: {
+            cliConfigError: new ProjectRootNotFoundError('No project root found'),
+            token: defaultMocks.token,
+          },
+        },
+      )
+
+      if (error) throw error
+      expect(stdout).toContain('projectId: flag-project')
+      expect(stdout).toContain('dataset: production')
+      expect(mockExportDataset).toHaveBeenCalledWith(
+        expect.objectContaining({dataset: 'production'}),
+      )
+    })
+
+    test('errors when outside project directory and no --project-id', async () => {
+      const {error} = await testCommand(
+        DatasetExportCommand,
+        ['production', 'output.tar.gz'],
+        {
+          mocks: {
+            cliConfigError: new ProjectRootNotFoundError('No project root found'),
+            token: defaultMocks.token,
+          },
+        },
+      )
+
+      expect(error).toBeInstanceOf(Error)
+      expect(error?.message).toContain('Unable to determine project ID')
+      expect(error?.oclif?.exit).toBe(1)
+    })
+
     test('validates dataset exists in project', async () => {
       const {mocks} = createTestContext({datasets: [{name: 'production'}]})
 

packages/@sanity/cli/src/commands/dataset/export.ts

@@ -3,12 +3,7 @@ import path from 'node:path'
 import {type Writable} from 'node:stream'
 
 import {Args, Flags} from '@oclif/core'
-import {
-  getProjectCliClient,
-  ProjectRootNotFoundError,
-  SanityCommand,
-  subdebug,
-} from '@sanity/cli-core'
+import {getProjectCliClient, SanityCommand, subdebug} from '@sanity/cli-core'
 import {boxen, input, spinner} from '@sanity/cli-core/ux'
 import {type DatasetsResponse} from '@sanity/client'
 import {exportDataset, type ExportOptions, type ExportProgress} from '@sanity/export'
@@ -131,14 +126,8 @@ export class DatasetExportCommand extends SanityCommand<typeof DatasetExportComm
     if (!dataset) {
       try {
         // Get default dataset from config (only available when running from a project directory)
-        let defaultDataset: string | undefined
-        try {
-          const cliConfig = await this.getCliConfig()
-          defaultDataset = cliConfig.api?.dataset
-        } catch (err) {
-          if (!(err instanceof ProjectRootNotFoundError)) throw err
-          // Not inside a project directory — no default dataset available
-        }
+        const cliConfig = await this.tryGetCliConfig()
+        const defaultDataset = cliConfig.api?.dataset
 
         if (defaultDataset) {
           dataset = defaultDataset

packages/@sanity/cli/src/commands/documents/__tests__/create.test.ts

@@ -3,7 +3,7 @@ import fs from 'node:fs/promises'
 import os from 'node:os'
 import path from 'node:path'
 
-import {getProjectCliClient} from '@sanity/cli-core'
+import {getProjectCliClient, ProjectRootNotFoundError} from '@sanity/cli-core'
 import {testCommand} from '@sanity/cli-test'
 import {watch as chokidarWatch} from 'chokidar'
 import {execa, execaSync} from 'execa'
@@ -921,4 +921,59 @@ describe('#documents:create', () => {
       }),
     )
   })
+
+  describe('outside project context', () => {
+    const noProjectRootMocks = {
+      cliConfigError: new ProjectRootNotFoundError('No project root found'),
+      token: 'test-token',
+    }
+
+    test('works with --project-id and --dataset flags when no project root', async () => {
+      const mockDoc = {_id: 'test-doc', _type: 'post', title: 'Test Post'}
+      const mockTransaction = vi.fn().mockReturnValue({
+        commit: vi.fn().mockResolvedValue({results: [{id: 'test-doc', operation: 'create'}]}),
+      })
+      mockGetProjectCliClient.mockResolvedValue({transaction: mockTransaction} as never)
+      mockFs.readFile.mockResolvedValue(JSON.stringify(mockDoc))
+      mockJson5.parse.mockReturnValue(mockDoc)
+
+      const {error, stdout} = await testCommand(
+        CreateDocumentCommand,
+        ['test-doc.json', '--project-id', 'my-project', '--dataset', 'production'],
+        {mocks: noProjectRootMocks},
+      )
+
+      if (error) throw error
+      expect(stdout).toContain('Created:')
+      expect(stdout).toContain('test-doc')
+      expect(mockGetProjectCliClient).toHaveBeenCalledWith(
+        expect.objectContaining({
+          dataset: 'production',
+          projectId: 'my-project',
+        }),
+      )
+    })
+
+    test('errors when no project root and no --project-id', async () => {
+      const {error} = await testCommand(CreateDocumentCommand, ['test-doc.json'], {
+        mocks: noProjectRootMocks,
+      })
+
+      expect(error).toBeInstanceOf(Error)
+      expect(error?.message).toContain('Unable to determine project ID')
+      expect(error?.oclif?.exit).toBe(1)
+    })
+
+    test('errors when no project root with --project-id but no --dataset', async () => {
+      const {error} = await testCommand(
+        CreateDocumentCommand,
+        ['test-doc.json', '--project-id', 'my-project'],
+        {mocks: noProjectRootMocks},
+      )
+
+      expect(error).toBeInstanceOf(Error)
+      expect(error?.message).toContain('No dataset specified')
+      expect(error?.oclif?.exit).toBe(1)
+    })
+  })
 })

packages/@sanity/cli/src/commands/documents/__tests__/delete.test.ts

@@ -1,3 +1,4 @@
+import {ProjectRootNotFoundError} from '@sanity/cli-core'
 import {testCommand} from '@sanity/cli-test'
 import {afterEach, describe, expect, test, vi} from 'vitest'
 
@@ -215,4 +216,63 @@ describe('#documents:delete', () => {
 
     expect(stdout).toContain('Deleted 2 documents')
   })
+
+  describe('outside project context', () => {
+    const noProjectRootMocks = {
+      cliConfigError: new ProjectRootNotFoundError('No project root found'),
+      token: 'test-token',
+    }
+
+    test('works with --project-id and --dataset flags when no project root', async () => {
+      const mockDelete = vi.fn()
+      const mockCommit = vi.fn().mockResolvedValue({
+        results: [{id: 'test-doc', operation: 'delete'}],
+      })
+      mockTransaction.mockReturnValue({
+        commit: mockCommit,
+        delete: mockDelete,
+      })
+
+      const {error, stdout} = await testCommand(
+        DeleteDocumentCommand,
+        ['test-doc', '--project-id', 'ext-project', '--dataset', 'ext-dataset'],
+        {mocks: noProjectRootMocks},
+      )
+
+      if (error) throw error
+      expect(stdout).toContain('Deleted 1 document')
+      expect(mockDelete).toHaveBeenCalledWith('test-doc')
+      expect(mockCommit).toHaveBeenCalled()
+      expect(mockGetProjectCliClient).toHaveBeenCalledWith(
+        expect.objectContaining({
+          dataset: 'ext-dataset',
+          projectId: 'ext-project',
+        }),
+      )
+    })
+
+    test('errors when no project root and no --project-id', async () => {
+      const {error} = await testCommand(
+        DeleteDocumentCommand,
+        ['test-doc', '--dataset', 'ext-dataset'],
+        {mocks: noProjectRootMocks},
+      )
+
+      expect(error).toBeInstanceOf(Error)
+      expect(error?.message).toContain('Unable to determine project ID')
+      expect(error?.oclif?.exit).toBe(1)
+    })
+
+    test('errors when no project root with --project-id but no --dataset', async () => {
+      const {error} = await testCommand(
+        DeleteDocumentCommand,
+        ['test-doc', '--project-id', 'ext-project'],
+        {mocks: noProjectRootMocks},
+      )
+
+      expect(error).toBeInstanceOf(Error)
+      expect(error?.message).toContain('No dataset specified')
+      expect(error?.oclif?.exit).toBe(1)
+    })
+  })
 })

packages/@sanity/cli/src/commands/documents/__tests__/get.test.ts

@@ -1,3 +1,4 @@
+import {ProjectRootNotFoundError} from '@sanity/cli-core'
 import {testCommand} from '@sanity/cli-test'
 import {afterEach, describe, expect, test, vi} from 'vitest'
 
@@ -17,14 +18,17 @@ const defaultMocks = {
 }
 
 const mockGetDocument = vi.hoisted(() => vi.fn())
+const mockGetProjectCliClient = vi.hoisted(() =>
+  vi.fn().mockResolvedValue({
+    getDocument: mockGetDocument,
+  }),
+)
 
 vi.mock('@sanity/cli-core', async () => {
   const actual = await vi.importActual('@sanity/cli-core')
   return {
     ...actual,
-    getProjectCliClient: vi.fn().mockResolvedValue({
-      getDocument: mockGetDocument,
-    }),
+    getProjectCliClient: mockGetProjectCliClient,
   }
 })
 
@@ -163,4 +167,76 @@ describe('#documents:get', () => {
     expect(error?.message).toContain('Missing 1 required arg')
     expect(error?.oclif?.exit).toBe(2)
   })
+
+  describe('outside project context', () => {
+    const noProjectRootMocks = {
+      cliConfigError: new ProjectRootNotFoundError('No project root found'),
+      token: 'test-token',
+    }
+
+    test('works with --project-id and --dataset flags when there is no project root', async () => {
+      const mockDoc = {
+        _id: 'test-doc',
+        _type: 'post',
+        title: 'Test Post',
+      }
+
+      mockGetDocument.mockResolvedValue(mockDoc)
+
+      const {error, stdout} = await testCommand(
+        GetDocumentCommand,
+        ['test-doc', '--project-id', 'flag-project', '--dataset', 'flag-dataset'],
+        {mocks: noProjectRootMocks},
+      )
+
+      if (error) throw error
+      expect(stdout).toContain('"_id": "test-doc"')
+      expect(stdout).toContain('"title": "Test Post"')
+      expect(mockGetDocument).toHaveBeenCalledWith('test-doc')
+    })
+
+    test('errors when outside project context and no --project-id provided', async () => {
+      const {error} = await testCommand(GetDocumentCommand, ['test-doc'], {
+        mocks: noProjectRootMocks,
+      })
+
+      expect(error).toBeInstanceOf(Error)
+      expect(error?.message).toContain('Unable to determine project ID')
+      expect(error?.oclif?.exit).toBe(1)
+    })
+
+    test('errors when outside project context with --project-id but no --dataset', async () => {
+      const {error} = await testCommand(
+        GetDocumentCommand,
+        ['test-doc', '--project-id', 'flag-project'],
+        {mocks: noProjectRootMocks},
+      )
+
+      expect(error).toBeInstanceOf(Error)
+      expect(error?.message).toContain('No dataset specified')
+      expect(error?.oclif?.exit).toBe(1)
+    })
+
+    test('--project-id flag overrides CLI config projectId', async () => {
+      const mockDoc = {
+        _id: 'test-doc',
+        _type: 'post',
+        title: 'Test Post',
+      }
+
+      mockGetDocument.mockResolvedValue(mockDoc)
+
+      const {error, stdout} = await testCommand(
+        GetDocumentCommand,
+        ['test-doc', '--project-id', 'override-project'],
+        {mocks: defaultMocks},
+      )
+
+      if (error) throw error
+      expect(stdout).toContain('"_id": "test-doc"')
+      expect(mockGetProjectCliClient).toHaveBeenCalledWith(
+        expect.objectContaining({projectId: 'override-project'}),
+      )
+    })
+  })
 })