CLI overview

One binary, two grammars

Everything TDE does from a shell goes through a single tde executable — but that executable routes your arguments to one of two different command grammars, and knowing which one you landed in explains most of the surprises.

The first is the semantic CLI. It is a strict, deterministic parser with no I/O of its own: it turns arguments into a typed contract that the Runtime executes over an owner-only socket. It owns task, project, pipeline, agent list, share, ask, chat, help and --version. It rejects unknown flags, duplicate options and conflicting combinations before anything runs, and it can emit a stable JSON envelope for every result.

The second is the desktop and operations CLI, a plain match on the first argument inside the desktop binary. It owns session, runtime, agent (the desktop driver), graph, doctor, diff, license, sync and the rest of the maintenance surface. Its subcommands are hand-parsed, so their help text, error messages and output shapes vary per command.

Dispatch order is what matters: the semantic CLI is offered every invocation first, and only when it declines does the argument fall through to the desktop match.

tde <args>
  │
  ├─ semantic CLI claims it?  →  strict parser → Runtime (semantic socket)
  │     task · project · pipeline · agent list · share · ask · chat
  │     help · --version · --help · -h
  │
  └─ otherwise               →  desktop binary match
        session · runtime · agent … · graph · doctor · diff · cron
        license · sync · bot · font · bootstrap · games · …
        (no argument at all → start the desktop)

The claim rule is exact. The semantic CLI takes the invocation when the first non-global argument is task, project, pipeline, share, ask, chat or help; when it is agent and the next word is list, --help or -h; or when it is --version, --help or -h. Running tde with no arguments at all is not a CLI invocation — it starts the terminal desktop.

Global options

Global options belong to the semantic CLI. They may appear anywhere in the command line, including after the subcommand, because they are stripped with their values before the root is identified.

tde --json task list --stage review
tde task list --json --stage review

Both lines above are the same command.

Getting help

tde help prints the global summary; tde help <topic> prints one command's usage. The same text is reachable by putting --help or -h after the command path you are asking about.

tde help
tde help task create
tde task create --help
tde share start -h

Valid topics are the command paths themselves: task, task create, task list, task show, task run, task watch, task logs, task cancel, task retry, task approve, task reject, task block, task unblock, task comment, project, project list, pipeline, pipeline list, agent, agent list, share, share start, share status, share url, share stop, ask and chat. An unknown topic exits with a usage error rather than guessing.

Commands on the other side of the split do not participate in tde help. They print their own usage line when called with no arguments or an unknown subcommand — tde runtime prints the Runtime usage block, tde session with an unknown verb prints the session usage block.

The JSON envelope

With --json, every semantic command prints exactly one line of JSON with a fixed outer shape. Success:

{"ok":true,"message":"…human summary…","data":{ … }}

Failure:

{"ok":false,"error":{"code":"missing_argument","message":"…","usage":"Usage: …"}}

data carries the structured result — a task, a page of tasks, an event page, a share status. usage is present only for usage errors, never for operational ones. Human output is sanitised of terminal control characters before printing; JSON output is left structured and lets the encoder escape control bytes, so an untrusted task title can never repaint your terminal.

Stable error codes: missing_argument, unknown_command, unknown_option, unexpected_argument, invalid_value, conflict, duplicate_option.

Command map

A few entry points exist purely for TDE to call itself and are not part of the supported surface: tde desktop, tde app-host, tde office-worker, tde demo and tde __version-probe.