refactor(cli): output format is a profile setting, not a flag

Drops `-o, --output`. Format is set once per profile with
`sim configure --set-output <format>`, or overridden ambiently with SIM_OUTPUT
for a one-off (`SIM_OUTPUT=json sim logs list | jq`) and for CI, which already
runs file-less on env alone.

Both remaining sources are ambient — set once, then read by every later command
— so an unrecognized value falls back to `table` rather than breaking the CLI.
There is no longer a strict tier, because there is no longer anything typed
per-invocation to be strict about.

Frees `-o` for `sim files download -o <path>`, which previously had to share the
short flag with a global that meant something else entirely.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EsThUPqZXjwuuyRjBbmVkj

Author: TheodoreSpeaks

packages/sim-cli/README.md

@@ -53,7 +53,7 @@ Each setting resolves independently, first match wins:
 
 | Rank | Source |
 | --- | --- |
-| 1 | Command-line flag (`--endpoint`, `--workspace`, `--output`) |
+| 1 | Command-line flag (`--endpoint`, `--workspace`) |
 | 2 | Environment (`SIM_ENDPOINT`, `SIM_API_KEY`, `SIM_WORKSPACE`, `SIM_OUTPUT`) |
 | 3 | `~/.sim/config` / `~/.sim/credentials` for the selected profile |
 | 4 | Built-in default (`https://sim.ai`, `table`) |
@@ -154,7 +154,9 @@ everything" default.
 
 ### Output formats
 
-`--output` / `-o`, or `SIM_OUTPUT`, or `output =` in the profile:
+Output format is a **profile setting**, not a per-command flag — there is no
+`--output`. Set it once with `sim configure --set-output <format>`, or override
+ambiently with `SIM_OUTPUT` for a one-off or for CI:
 
 | Format | For |
 | --- | --- |
@@ -169,20 +171,23 @@ duration stays `1500`, not `"1.5s"` — so switching format never changes the da
 parsing.
 
 ```bash
-sim logs list --level error -o json | jq -r '.[].executionId'
-sim logs list --level error -o yaml > logs.yaml
+sim configure --set-output json                      # for this profile, from now on
+sim configure --set-output text --profile scripts    # a profile dedicated to scripting
 
-sim files list -o text | while IFS=$'\t' read -r id name size type uploaded; do
+SIM_OUTPUT=json sim logs list --level error | jq -r '.[].executionId'
+SIM_OUTPUT=yaml sim logs list --level error > logs.yaml
+
+SIM_OUTPUT=text sim files list | while IFS=$'\t' read -r id name size type uploaded; do
   echo "$id $name"
 done
 ```
 
 An absent value is an em-dash in `table` and an **empty field** in `text`, so
 emptiness tests downstream behave.
 
-A bad `--output` is an error; a bad `SIM_OUTPUT` or `output =` is ignored and
-falls back to `table` — ambient settings should not brick every command, but a
-flag you just typed should not be silently disregarded.
+A bad `SIM_OUTPUT` or `output =` is ignored and falls back to `table`. Both are
+ambient — set once, then read by every later command — so one bad value should
+not break the CLI outright.
 
 ## How this stays in sync with the API
 

packages/sim-cli/src/config/profile.test.ts

@@ -97,10 +97,23 @@ describe('profile resolution', () => {
   })
 
   it('ignores an unrecognized output format instead of failing the whole resolve', () => {
-    // Ambient sources tolerate garbage so one bad value cannot brick every
-    // command; the `--output` flag is strict instead (commander `.choices`).
+    // Both output sources are ambient — set once, then every later command reads
+    // them — so a bad value falls back rather than breaking the CLI outright.
     process.env.SIM_OUTPUT = 'xml'
     expect(resolveProfile().output).toBe('table')
+
+    process.env.SIM_OUTPUT = undefined
+    writeConfigProfile('default', { output: 'xml' })
+    expect(resolveProfile().output).toBe('table')
+  })
+
+  it('takes the output format from the profile, and lets the env override it', () => {
+    // There is deliberately no `--output` flag: format is a profile setting.
+    writeConfigProfile('default', { output: 'yaml' })
+    expect(resolveProfile()).toMatchObject({ output: 'yaml', sources: { output: 'config' } })
+
+    process.env.SIM_OUTPUT = 'json'
+    expect(resolveProfile()).toMatchObject({ output: 'json', sources: { output: 'env' } })
   })
 
   it('accepts every documented output format from the environment', () => {

packages/sim-cli/src/config/profile.ts

@@ -47,7 +47,6 @@ export interface ProfileOverrides {
   endpoint?: string
   apiKey?: string
   workspaceId?: string
-  output?: string
 }
 
 /**
@@ -186,9 +185,13 @@ export function resolveProfile(overrides: ProfileOverrides = {}): ResolvedProfil
     'unset'
   )
 
+  /**
+   * No flag tier: output format is a profile setting, not a per-command one.
+   * `SIM_OUTPUT` stays as the one-off escape hatch (`SIM_OUTPUT=json sim … | jq`)
+   * and as the file-less path for CI, but there is deliberately no `--output`.
+   */
   const output = resolve<OutputFormat>(
     [
-      ['flag', parseOutput(overrides.output)],
       ['env', parseOutput(process.env.SIM_OUTPUT)],
       ['config', parseOutput(config.output)],
     ],

packages/sim-cli/src/context.ts

@@ -7,7 +7,6 @@ export interface GlobalOptions {
   profile?: string
   endpoint?: string
   workspace?: string
-  output?: string
 }
 
 /**
@@ -25,7 +24,6 @@ export function profileFrom(command: Command, extra: ProfileOverrides = {}): Res
     profile: globals.profile,
     endpoint: globals.endpoint,
     workspaceId: globals.workspace,
-    output: globals.output,
     ...extra,
   })
 }

packages/sim-cli/src/index.ts

@@ -1,15 +1,14 @@
 #!/usr/bin/env node
 
 import chalk from 'chalk'
-import { Command, Option } from 'commander'
+import { Command } from 'commander'
 import { loginCommand, logoutCommand, profilesCommand, whoamiCommand } from './commands/auth.js'
 import { configureCommand } from './commands/configure.js'
 import { filesCommand } from './commands/files.js'
 import { knowledgeCommand } from './commands/knowledge.js'
 import { logsCommand } from './commands/logs.js'
 import { tablesCommand } from './commands/tables.js'
 import { workflowsCommand } from './commands/workflows.js'
-import { OUTPUT_FORMATS } from './config/index.js'
 import { SimApiError } from './http/client.js'
 
 const program = new Command()
@@ -21,16 +20,6 @@ program
   .option('-p, --profile <name>', 'Profile to use (env: SIM_PROFILE)')
   .option('--endpoint <url>', 'Sim deployment to talk to (env: SIM_ENDPOINT)')
   .option('-w, --workspace <id>', 'Workspace to target (env: SIM_WORKSPACE)')
-  // `.choices` so a typo'd format is an error, not a silent fall back to
-  // `table`. Deliberately stricter than SIM_OUTPUT and the config file, which
-  // tolerate an unknown value: those are ambient and set once, and a bad one
-  // should not make every command fail — but a flag is an instruction just
-  // typed, so honouring something else is a lie.
-  .addOption(
-    new Option('-o, --output <format>', 'Output format (env: SIM_OUTPUT)').choices([
-      ...OUTPUT_FORMATS,
-    ])
-  )
 
 program.addCommand(loginCommand())
 program.addCommand(logoutCommand())
@@ -54,6 +43,7 @@ Examples:
   $ sim login --profile dev --endpoint http://localhost:3000
   $ sim workflows list
   $ sim logs list --level error --limit 20
+  $ sim configure --set-output json           Output format is a profile setting
   $ sim knowledge search "refund policy" --kb kb_123
   $ sim whoami --profile dev
 `