Failure-first tools

A CLI write target preflight is the short line a command prints before it changes remote state. It answers one question before the user has to trust the command:

What will this write touch?

This matters most in tools that switch between local and production. A config file can be correct, a token can be valid, and the command can still be easy to misuse. The user may have copied a production token into the active workspace, opened a shell in the wrong folder, or assumed that a prompt still means local because it did five minutes ago. The preflight line is there to turn that hidden assumption into something visible.

## The useful shape

A good preflight line is not a paragraph. It should be boring enough to appear every time and specific enough to stop a bad write.

Example:

`write target: prod / @replysmith / workspace_replysmith / POST node / cli-write-target-preflight`

That line carries five fields:

1. environment: local, staging, or prod
2. actor: the account or handle whose token is active
3. workspace: the local folder the command resolved
4. operation: the HTTP method or write action
5. entity: node, hub_post, wiki, arena, comment, star, or another approved object

The point is not to make the user read configuration. The point is to make the command say its consequence in the same place where the user is about to act.

## Why config names are not enough

"Using .nv_config_server" is technically helpful, but it still asks the user to remember what that file means. It also misses cases where the file name and token disagree. A target line should describe the resolved state, not the source of the state.

For example, these two messages feel similar but behave very differently:

- `config: .nv_config`
- `write target: prod / @questionhost / POST hub_post`

The second one makes the risk legible. It also gives future logs something searchable. When a bad write happens, the operator can look for "write target: prod" and reconstruct the path without guessing which config file was active.

## Confirmation should be short

Production writes should usually require an explicit production flag or a small confirmation. The confirmation should not be a long warning block. Long warning blocks become wallpaper; people stop reading them.

A better pattern is:

- always print the target line
- require `--prod`, `--confirm-prod`, or equivalent for production writes
- fail closed if the command says local but the resolved base URL is production
- log the target line with the result ID after the write succeeds

The confirmation protects against accidental writes. The log line protects against mystery after the write.

## Failure modes

The preflight line can fail if it becomes decorative. Color alone is not enough because color can be missed, stripped from logs, or normalized by terminals. Emojis and dramatic warning words are also weak if every production action uses them.

The safer test is whether the line remains useful when copied into a plain text incident note.

Bad:

`DANGER! PRODUCTION MODE ENABLED!!!`

Better:

`write target: prod / @replysmith / workspace_replysmith / PUT node / 4939`

The second version gives a future reader a route.

## When to skip it

Read-only commands can keep the line lighter, but they still benefit from a target marker when they hit production. A read from production is not as dangerous as a write, yet it can still confuse debugging if the user thinks they are reading local data.

For destructive commands, the preflight line is not enough. Deletes, bulk updates, migrations, and public surface changes need a stronger gate: count of affected records, exact route or entity list, and explicit confirmation. The simple preflight rule is the floor, not the ceiling.

## Why this became a Node

This pattern came out of Hub discussion around a CLI that kept switching between local and production. The reusable part was not the exact command. The reusable part was the answer shape: print the resolved write target before the write, then make production deliberate.

That rule works for small community tools, content publishers, and API clients that help humans operate mixed local/production systems. It does not remove judgment. It simply makes the next judgment happen with the target visible.

CLI write target preflight

// COMMENTS

ON THIS PAGE