feat(cli): default --wait in non-interactive mode, slim init --help

packages/@sanity/cli/src/actions/auth/login/login.ts

@@ -1,4 +1,5 @@
 import {
+  clearCliTokenCache,
   type CLITelemetryStore,
   getCliToken,
   getUserConfig,
@@ -13,7 +14,7 @@
 import {canLaunchBrowser} from '../../../util/canLaunchBrowser.js'
 import {startServerForTokenCallback} from '../authServer.js'
 import {getBackgroundLoginConfigPath, startBackgroundLogin} from '../backgroundLogin.js'
 import {validateSession} from '../ensureAuthenticated.js'
 import {getProvider} from './getProvider.js'
 import {storeAuthToken} from './storeAuthToken.js'
 import {validateToken} from './validateToken.js'
@@ -107,6 +108,10 @@
       const interval = 3000
       const deadline = Date.now() + maxWait
       while (Date.now() < deadline) {
+        // The background child writes the new token to disk in a separate
+        // process, which can't invalidate this process's in-memory token cache.
+        // Clear the cache so validateSession re-reads from disk each iteration.
+        clearCliTokenCache()
         const user = await validateSession()
         if (user) {
           output.log(`Logged in as ${user.email}.`)

packages/@sanity/cli/src/actions/init/initAction.ts

@@ -2,7 +2,12 @@ import {readFile} from 'node:fs/promises'
 import path from 'node:path'
 import {styleText} from 'node:util'
 
-import {type SanityOrgUser, subdebug, type TelemetryUserProperties} from '@sanity/cli-core'
+import {
+  clearCliTokenCache,
+  type SanityOrgUser,
+  subdebug,
+  type TelemetryUserProperties,
+} from '@sanity/cli-core'
 import {logSymbols, spinner} from '@sanity/cli-core/ux'
 import {type TelemetryTrace} from '@sanity/telemetry'
 import {type Framework, frameworks} from '@vercel/frameworks'
@@ -402,12 +407,15 @@ async function ensureAuthenticated(
       throw new InitError(`Login failed: ${message}`, 1)
     }
 
-    // Background login returns immediately; poll for the token
+    // Background login returns immediately; poll for the token. The child
+    // writes to disk in another process, so clear the in-memory cache each
+    // iteration to force a fresh disk read.
     const maxWait = 120_000
     const interval = 3000
     const deadline = Date.now() + maxWait
     let loggedInUser: SanityOrgUser | null = null
     while (Date.now() < deadline) {
+      clearCliTokenCache()
       loggedInUser = await validateSession()
       if (loggedInUser) break
       await new Promise((r) => setTimeout(r, interval))

packages/@sanity/cli/src/commands/__tests__/login.test.ts

@@ -1321,7 +1321,7 @@ describe('#login', {timeout: 10_000}, () => {
         providers: [{name: 'google', title: 'Google', url: 'https://api.sanity.io/auth/google'}],
       })
 
-      const {error, stdout} = await testCommand(LoginCommand, [])
+      const {error, stdout} = await testCommand(LoginCommand, ['--no-wait'])
 
       if (error) throw error
       expect(stdout).toContain('Opening browser at')
@@ -1344,7 +1344,7 @@ describe('#login', {timeout: 10_000}, () => {
         providers: [{name: 'google', title: 'Google', url: 'https://api.sanity.io/auth/google'}],
       })
 
-      const {error, stdout} = await testCommand(LoginCommand, ['--no-open'])
+      const {error, stdout} = await testCommand(LoginCommand, ['--no-open', '--no-wait'])
 
       if (error) throw error
       expect(stdout).toContain('Please open a browser at')

packages/@sanity/cli/src/commands/init.ts

@@ -10,7 +10,15 @@ import {getSanityEnv} from '../util/getSanityEnv.js'
 
 export class InitCommand extends SanityCommand<typeof InitCommand> {
   static override args = {type: Args.string({hidden: true})}
-  static override description = 'Initialize a new Sanity Studio, project and/or app'
+  static override description = `Initialize a new Sanity Studio, project and/or app.
+
+Common usage (unattended):
+  sanity init -y --project-name "my-app" --dataset production --output-path ./studio
+  sanity init -y --bare --project-name "my-app" --organization <id>
+  sanity init -y --project <existing-id> --dataset production --output-path .
+
+If multiple organizations or providers exist, the CLI prints the IDs with a
+copy-pasteable hint. Run 'sanity organizations list' to discover IDs.`
   static override enableJsonFlag = true
 
   static override examples = [
@@ -35,6 +43,11 @@ export class InitCommand extends SanityCommand<typeof InitCommand> {
         '<%= config.bin %> <%= command.id %> -y --project-name "Movies Unlimited" --dataset moviedb --visibility private --template moviedb --output-path /Users/espenh/movies-unlimited',
       description: 'Create a brand new project with name "Movies Unlimited"',
     },
+    {
+      command: 'cd my-studio && sanity typegen generate',
+      description:
+        'After init, generate TypeScript types from your schema (avoid hand-writing interfaces)',
+    },
   ] satisfies Array<Command.Example>
 
   static override flags = {
@@ -53,6 +66,7 @@ export class InitCommand extends SanityCommand<typeof InitCommand> {
         'Optionally select a coupon for a new project (cannot be used with --project-plan)',
       exclusive: ['project-plan'],
       helpValue: '<code>',
+      hidden: true,
     }),
     'create-project': Flags.string({
       deprecated: {message: 'Use --project-name instead'},
@@ -95,11 +109,13 @@ export class InitCommand extends SanityCommand<typeof InitCommand> {
       allowNo: true,
       default: undefined,
       description: 'Import template sample dataset',
+      hidden: true,
     }),
     mcp: Flags.boolean({
       allowNo: true,
       default: true,
       description: 'Enable AI editor integration (MCP) setup',
+      hidden: true,
     }),
     'nextjs-add-config-files': Flags.boolean({
       allowNo: true,
@@ -139,6 +155,7 @@ export class InitCommand extends SanityCommand<typeof InitCommand> {
       allowNo: true,
       default: undefined,
       description: 'Overwrite existing files',
+      hidden: true,
     }),
     'package-manager': Flags.string({
       description: 'Specify which package manager to use [allowed: npm, yarn, pnpm]',
@@ -160,6 +177,7 @@ export class InitCommand extends SanityCommand<typeof InitCommand> {
     'project-plan': Flags.string({
       description: 'Optionally select a plan for a new project',
       helpValue: '<name>',
+      hidden: true,
     }),
     provider: Flags.string({
       description: 'Login provider to use',

packages/@sanity/cli/src/commands/login.ts

@@ -69,8 +69,9 @@ authenticated, this completes in seconds.`
       helpValue: '<name>',
     }),
     wait: Flags.boolean({
-      default: false,
-      description: 'Block until login completes (up to 5 minutes). Recommended for agents and CI.',
+      allowNo: true,
+      description:
+        'Block until login completes (up to 5 minutes). Defaults to true in non-interactive contexts (CI, agents); pass `--no-wait` to opt out.',
     }),
     'with-token': Flags.boolean({
       description: 'Read token from standard input',
@@ -82,6 +83,12 @@ authenticated, this completes in seconds.`
     const {flags} = await this.parse(LoginCommand)
     const {'sso-provider': ssoProvider, 'with-token': withToken, ...loginFlags} = flags
 
+    // Default `--wait` to true when not interactive and not using --with-token,
+    // so agents and CI get a deterministic exit code without having to discover
+    // the flag. Pass `--no-wait` to opt out.
+    const effectiveWait =
+      typeof flags.wait === 'boolean' ? flags.wait : !isInteractive() && !withToken
+
     try {
       const token = withToken ? await readTokenFromStdin() : undefined
 
@@ -91,9 +98,10 @@ authenticated, this completes in seconds.`
         ssoProvider,
         telemetry: this.telemetry,
         token,
+        wait: effectiveWait,
       })
 
-      if (isInteractive() || token || flags.wait) {
+      if (isInteractive() || token || effectiveWait) {
         this.log('Login successful')
       }
     } catch (error) {

packages/@sanity/cli/src/commands/tokens/__tests__/add.test.ts

@@ -93,6 +93,7 @@ describe('#tokens:add', () => {
     expect(stdout).toContain('Role: Viewer')
     expect(stdout).toContain('Token: sk_test_abcd1234')
     expect(stdout).toContain('Copy the token above')
+    expect(stdout).toContain('SANITY_API_TOKEN=sk_test_abcd1234')
   })
 
   test('creates token with specific role', async () => {

packages/@sanity/cli/src/commands/tokens/add.ts

@@ -99,6 +99,9 @@ export class AddTokenCommand extends SanityCommand<typeof AddTokenCommand> {
       this.log(`Token: ${token.key}`)
       this.log('')
       this.log('Copy the token above – this is your only chance to do so!')
+      this.log('')
+      this.log('Add to .env (or your environment) for use with @sanity/client:')
+      this.log(`  SANITY_API_TOKEN=${token.key}`)
     } catch (error) {
       const err = error as Error