terminalkoctl list --json for scripts #16

New issue

Open

opened 2026-08-19 23:57:41 +00:00 by dusan · 0 comments

dusan commented

2026-08-19 23:57:41 +00:00

Owner

Context

terminalkoctl list prints a table:

STATE       RUNNING           FOLDER                    NAME
running     vim               Work                      api server
stopped     —                 —                         notes

docs/spec/command-line.md says plainly that this table is for people and is not
a stable interface, and that anything needing to parse it should get a flag
instead. This issue is that flag.

The data behind it is already structured: terminalko_proto::SessionInfo carries
the id, state, working directory and foreground program, and the CLI merges that
with the configuration to add names and folders
(crates/terminalko-ctl/src/main.rs, list).

Work

terminalkoctl list --json printing one JSON array of objects: id, name,
folder (null when unfiled), state, program (null when not running or
unreadable), cwd, and the session's type. Nothing else, so the shape stays
small enough to keep stable;
serde_json is already in the workspace (the agent uses it for container
discovery), so no new dependency;
the state strings are the machine-readable part that matters most: use the
protocol's own names (stopped, starting, running, exited, failed)
rather than the table's prose, and document that an exited entry carries its
code;
consider whether start/stop need it. They print one line and set an exit
status, which is already scriptable; adding --json there is probably noise.
Say which way you went.

Acceptance criteria

terminalkoctl list --json emits valid JSON — verified by piping it through a
parser in the test, not by eye.
Every session that appears in the table appears in the JSON, including sessions
the agent still has but the configuration no longer mentions.
With no agent running, the JSON is still emitted, with everything stopped, and
the note about there being no agent goes to stderr so stdout stays parseable.
The extended integration test (crates/terminalko-ctl/tests/cli.rs, which needs
no display) covers both the with-agent and without-agent cases.
docs/spec/command-line.md documents the exact keys and states, and says they
are the stable part.

Notes

Keep the human table as the default. Changing the default output would break
the one interface people actually use.

## Context `terminalkoctl list` prints a table: ```text STATE RUNNING FOLDER NAME running vim Work api server stopped — — notes ``` `docs/spec/command-line.md` says plainly that this table is for people and is not a stable interface, and that anything needing to parse it should get a flag instead. This issue is that flag. The data behind it is already structured: `terminalko_proto::SessionInfo` carries the id, state, working directory and foreground program, and the CLI merges that with the configuration to add names and folders (`crates/terminalko-ctl/src/main.rs`, `list`). ## Work * `terminalkoctl list --json` printing one JSON array of objects: `id`, `name`, `folder` (null when unfiled), `state`, `program` (null when not running or unreadable), `cwd`, and the session's `type`. Nothing else, so the shape stays small enough to keep stable; * `serde_json` is already in the workspace (the agent uses it for container discovery), so no new dependency; * the state strings are the machine-readable part that matters most: use the protocol's own names (`stopped`, `starting`, `running`, `exited`, `failed`) rather than the table's prose, and document that an `exited` entry carries its code; * consider whether `start`/`stop` need it. They print one line and set an exit status, which is already scriptable; adding `--json` there is probably noise. Say which way you went. ## Acceptance criteria - `terminalkoctl list --json` emits valid JSON — verified by piping it through a parser in the test, not by eye. - Every session that appears in the table appears in the JSON, including sessions the agent still has but the configuration no longer mentions. - With no agent running, the JSON is still emitted, with everything stopped, and the note about there being no agent goes to **stderr** so stdout stays parseable. - The extended integration test (`crates/terminalko-ctl/tests/cli.rs`, which needs no display) covers both the with-agent and without-agent cases. - `docs/spec/command-line.md` documents the exact keys and states, and says they are the stable part. ## Notes - Keep the human table as the default. Changing the default output would break the one interface people actually use.

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

dusan/terminalko#16

No description provided.

Rows
Columns