LINZ CLI: Idealized Interface Spec & Command Compatibility Matrix (Current → Idealized)

linz_cli_compatibility_matrix.md

LINZ CLI
Compatibility Matrix: Current → Idealized
_{March 4, 2026 - Sean Grove & Codex}

---

Status Legend

Status	Meaning
🟢 direct	Same semantics, renamed surface
🔵 composed	Represented by a richer or combined command
🟣 expanded	Idealized command adds significant new flags/output behavior

---

Session Commands

Current	Idealized	Status	Notes
linz status [selector]	linz session get [--target <selector>]	🟢 direct	Adds canonical selector and field selection
linz sessions	linz session list	🟣 expanded	Adds --filter, --sort, --fields, --limit
linz tree	linz session tree	🟣 expanded	Adds --root, --max-depth, --only-issues, --stats
linz name <slug> --from <sel>	linz session set --target <sel> --slug <slug>	🟢 direct	Cleaner verb

Instance Commands

Current	Idealized	Status	Notes
linz generate	linz instance id-generate	🟢 direct	Namespaced under instance
linz create [instance_id]	linz instance create [--id <lz...>]	🟢 direct	Adds tags at create
linz fork [--from <sel>] [child_id]	linz instance clone [--source <sel>] [--id <lz...>]	🟢 direct	Clear source/child naming
linz exec <sel> -- <cmd>	linz instance run --target <sel> -- <cmd>	🟢 direct	Unifies execution verb
linz shell <sel> [-- <cmd>]	linz instance open --target <sel> [-- <cmd>]	🟢 direct	Explicitly interactive/open semantics
linz pull <sel>	linz instance pull --target <sel>	🟢 direct	Adds --into and --merge-here
linz call -- <cmd>	linz instance run --mode oneshot -- <cmd>	🔵 composed	Makes composition explicit
linz stop <sel>	linz instance stop --target <sel>	🟢 direct	Canonical selector
linz prune <sel>	linz instance delete --target <sel> [--force]	🟢 direct	delete clearer than prune

Message Commands

Current	Idealized	Status	Notes
linz inbox / list	linz message list	🟢 direct	Message noun normalization
linz inbox read <id>	linz message read <id>	🟢 direct
linz inbox ack <id>	linz message ack <id>	🟢 direct
linz inbox clear	linz message clear	🟢 direct
linz inbox send <sel> <json>	linz message send --target <sel> --payload <json>	🟢 direct	Adds --kind, --idempotency-key

Network Commands

Current	Idealized	Status	Notes
linz network list	linz network list	🟢 direct	Adds filter semantics
linz network request --tcp/--udp --local <port>	linz network request --protocol <tcp|udp> --local <port>	🟢 direct	Protocol flag normalization
linz network release --tcp/--udp --external <port>	linz network release --protocol <tcp|udp> --external <port>	🟢 direct	Protocol flag normalization
linz http <port>	linz network url --port <port>	🟢 direct	Key equivalence

Domain Commands

Current	Idealized	Status	Notes
linz domain list	linz domain list	🟢 direct	Adds filtering
linz domain bind <domain> --from <sel> --port <n>	linz domain bind <domain> --target <sel> --port <n>	🟢 direct	--target unification
linz domain unbind <domain>	linz domain unbind <domain>	🟢 direct

Initd Commands

Current	Idealized	Status	Notes
linz initd current	linz initd get	🟢 direct
linz initd set <instance_id>	linz initd set --target <selector>	🟢 direct	Canonical target model
N/A	linz initd logs	🟣 expanded	New helper for stdout/stderr refs

Admin Commands

Current	Idealized	Status	Notes
linz dev claim	linz admin policy claim-dev	🟢 direct	Namespaced admin flow
linz unlink ssh key	linz admin auth unlink-ssh-keys	🟢 direct	Normalized auth noun
linz force-restart	linz admin node force-restart --scope local --yes	🟢 direct	Safer confirmation pattern

Schema Commands

Current	Idealized	Status	Notes
linz <cmd> --json-schema	linz schema print <group> <verb>	🟣 expanded	Central schema path

---

Summary

Status	Count
🟢 Direct	24
🔵 Composed	1
🟣 Expanded	5
Total	30

---

Backward Compatibility Policy

1. Legacy aliases: Keep all current commands as aliases for at least one major release
2. Deprecation warnings: Emit in text mode and meta.warnings[] in JSON mode
3. Strict mode: Enforce via LINZ_CLI_STRICT=1 in CI before removing aliases

Explicit Equivalence

Current:    linz http 3000
Idealized:  linz network url --port 3000

linz_help_spec.md

LINZ CLI
Idealized Interface Specification
_{March 4, 2026 - Sean Grove & Codex}

---

Overview

A complete, coherent, noun-first linz help surface with explicit docstrings, explicit flags, concrete examples, strong JSON-first automation ergonomics, and backwards-compatible migration from the current CLI.

Key Decisions

Decision	Decided by
initd remains canonical in near-term interface naming	Sean, Codex
Canonical target selection uses --target <selector> across all targetable commands	Sean, Codex
linz http <PORT> maps to linz network url --port <PORT>	Sean, Codex

---

Top-Level Interface

linz [GLOBAL FLAGS] <GROUP> <VERB> [ARGS] [FLAGS] [-- COMMAND...]
linz help [GROUP] [VERB]
linz schema print <GROUP> <VERB>
linz completion generate <bash|zsh|fish>

Manage LINZ runtime sessions, instances, messaging, networking, domains, init startup behavior, and administrative controls.

---

Groups

Group	Description
session	Session identity and topology operations
instance	Runtime instance lifecycle and command execution
message	Inbox messaging operations
network	Port binding and proxy URL operations
domain	Custom domain operations
initd	Startup init target operations
admin	Policy, auth, and node maintenance
schema	Output schema operations
completion	Shell completion generation

---

Global Flags

Flag	Description	Default
--format <table|json|yaml|tree>	Output format	table
--json	Shortcut for --format json	-
--target <selector>	Canonical selector for targetable commands	-
--profile <name>	CLI profile for host/auth defaults	-
--timeout <duration>	Max wait time (e.g. 10s, 2m)	-
--no-color	Disable ANSI colors	-
--verbose	Include request diagnostics and debug context	-
--help	Show help text	-
--version	Show CLI version	-

Target Selector Forms

instance:<lz[a-z2-7]{20}>       # by instance ID
session:<sess_lz[a-z2-7]{20}>   # by session ID
slug:<session_slug>              # by named slug

---

session - Session Identity & Topology

Read and mutate session identity and topology state.

Verbs

Verb	Description
get	Get one resolved session identity and policy
list	List sessions visible to current linked user
tree	Render session lineage tree
set	Mutate session metadata (slug, tags)
reconcile	Repair metadata inconsistencies
gc	Garbage-collect stale/pruned session metadata

session get

linz session get [--target <selector>] [--parent] [--fields <csv>]

Flag	Description
--parent	Resolve one level above selected session
--fields <csv>	Restrict output fields

linz session get --target instance:lzabc...
linz session get --target slug:main --parent

session list

linz session list [--filter <expr>] [--sort <field>] [--fields <csv>] [--limit <n>]

Flag	Description
--filter <expr>	Filter expression (e.g. state=running,tag.team=kandan)
--sort <field>	Sort by last_connected_at, created_at, slug
--fields <csv>	Columns/keys to return
--limit <n>	Limit rows

linz session list --filter state=running --sort last_connected_at
linz session list --format json --fields session_id,instance_id,state

session tree

linz session tree [--root <selector>] [--max-depth <n>] [--only-issues] [--stats]

Flag	Description
--root <selector>	Restrict tree to one root
--max-depth <n>	Limit depth
--only-issues	Show nodes with diagnostics only
--stats	Include summary stats block

linz session tree --stats
linz session tree --root slug:main --max-depth 3 --format json

session set

linz session set --target <selector> [--slug <value>] [--tag k=v ...] [--untag <key> ...]

Flag	Description
--slug <value>	Set session slug
--tag <k=v>	Add or replace a tag (repeatable)
--untag <key>	Remove tag key (repeatable)

linz session set --target slug:main --slug prod-main
linz session set --target slug:main --tag team=kandan --tag env=prod

session reconcile

linz session reconcile [--fix-missing-created-sessions]

linz session reconcile --fix-missing-created-sessions --format json

session gc

linz session gc [--pruned-older-than <duration>] [--yes]

linz session gc --pruned-older-than 7d --yes

---

instance - Runtime Lifecycle & Execution

Manage runtime instance lifecycle, execution, and artifact movement.

Verbs

Verb	Description
id-generate	Generate a valid instance ID
create	Create a new runtime instance
clone	Create a child from parent snapshot
run	Run command in existing instance or oneshot branch workflow
open	Open interactive shell in instance
pull	Copy target /home/linz into local output path
stop	Stop running instance
delete	Stop and remove instance (prune)

instance create

linz instance create [--id <lz...>] [--tag k=v ...]

linz instance create
linz instance create --id lzabcdefghijklmnopqrst --tag team=kandan

instance clone

linz instance clone [--source <selector>] [--id <lz...>]

linz instance clone --source slug:main
linz instance clone --source instance:lzabc... --id lzdef...

instance run

linz instance run --target <selector> [--wait] -- <COMMAND...>
linz instance run --mode oneshot [--output <path>] -- <COMMAND...>

Flag	Description
--mode <direct|oneshot>	direct: run in selected instance. oneshot: clone, run, pull, message, stop
--output <path>	Output base path for pulled artifacts
--wait	Wait for command completion

linz instance run --target slug:main -- "git status"
linz instance run --mode oneshot -- "opencode run implement-x"

instance open

linz instance open --target <selector> [-- COMMAND...]

linz instance open --target slug:main
linz instance open --target instance:lzabc... -- echo hello

instance pull

linz instance pull --target <selector> [--into <path>] [--merge-here]

Flag	Description
--into <path>	Destination base directory
--merge-here	Merge directly into current directory (safety checks apply)

linz instance pull --target instance:lzabc...
linz instance pull --target session:sess_lzabc... --into /home/linz/runs

instance stop / instance delete

linz instance stop --target instance:lzabc...
linz instance delete --target instance:lzabc... --force

---

message - Inbox Messaging

Operate inbox message envelopes between sessions.

Verbs

Verb	Description
list	List inbox message envelopes
read	Read one message envelope
ack	Acknowledge one message envelope
clear	Clear all inbox messages for current session
send	Send JSON payload to another session

message send

linz message send --target <selector> --payload <json> [--kind <value>] [--idempotency-key <value>]

linz message send --target slug:main --payload '{"text":"hello"}'
linz message send --target session:sess_lzabc... --kind status --payload '{"ok":true}'

message list / read / ack / clear

linz message list --unacked --json
linz message read msg_abc123 --json
linz message ack msg_abc123 --json
linz message clear --json

---

network - Port Binding & Proxy URLs

Manage externally reachable transport for runtime services.

Verbs

Verb	Description
request	Allocate external binding for protocol + local port
release	Release external binding
list	List network bindings
url	Build proxy URL for target instance and port

network request / release

linz network request --protocol tcp --local 4140
linz network request --protocol udp --local 7777 --target slug:main
linz network release --protocol tcp --external 24000

network url

linz network url --port 3000
linz network url --target slug:main --port 4140 --json

---

domain - Custom Domains

Manage custom domain bindings and certificate state.

linz domain bind serve.example.com --target slug:main --port 4140
linz domain unbind serve.example.com
linz domain list --filter status=active --json

---

initd - Startup Init

Manage startup init script target for linked user.

Verb	Description
get	Show current initd target instance
set	Set current initd target instance
logs	Show initd stdout/stderr references

linz initd get --json
linz initd set --target instance:lzabcdefghijklmnopqrst
linz initd logs --stream stderr --tail 200

---

admin - Policy, Auth & Node Maintenance

linz admin policy claim-dev
linz admin policy claim-dev --code "$LINZ_DEV_LOGIN_CODE"
linz admin auth unlink-ssh-keys --json
linz admin node force-restart --scope local --yes

---

schema & completion

linz schema print session get
linz schema print network request
linz completion generate zsh