The 14 commands

issues-fs-cli 0.3.0: 17 source files, 1,080 LOC, 94 tests, built on Typer. Fourteen commands, three output formats, and --for-agent on every single one. Everything below was read out of the command source rather than out of a README.

Every command, every flag

The flag that is the story

Every one of the fourteen commands takes --for-agent, and it forces JSON regardless of what --output says.

It is worth being clear about why this is more than a convenience. --for-agent is not a mode. There is no agent subcommand, no separate binary, no JSON-only build. It is one flag added to the command you were already going to run, which means:

• A human and an agent run the same command and each gets a form they can use. Nothing needs to be documented twice.
• An agent that only knows one thing about this tool — append --for-agent — can drive all fourteen commands correctly.
• It cannot drift out of parity with the human surface, because it is the same code path with the formatter pinned.

Combined with lite mode and the .issues DSL, this is the third of three agent-operable surfaces. No other project in the estate has three, and no document in the corpus says so.

Output formats

Selected with --output/-o on the eleven commands that produce readable output. types init is the exception: it initialises rather than reports, so it takes only --for-agent.

Two warts, documented rather than hidden

How the CLI finds your graph

CLI__Context.discover_issues_root()   # walks UP from cwd looking for .issues/

Exactly like git. You can run issues-fs list from six directories deep in the project and it finds the same graph. There is no configuration file naming a repository, no environment variable, and no daemon holding a path — the location of the data is the location of the folder, which is the same reason the tracker travels with a clone.

Recipes

# everything open, as a table
issues-fs list --status open

# every bug, as JSON, for a script
issues-fs list --type bug --output json

# a node and everything two hops out
issues-fs show Task-1 --depth 2

# what is this blocking, and what is blocking it
issues-fs links Task-1

# close something and record why
issues-fs update Task-1 --status done
issues-fs comment Task-1 "Published at /shipped/; verified against live PyPI" --author site-agent

# the whole graph, as JSON, for an agent to reason over
issues-fs list --for-agent

What the CLI does not do

Worth stating, because the absences are informative rather than accidental:

• No server, no watch mode, no sync. Every command is a single read or write against the filesystem and then exits.
• No node-type authoring. types init writes the defaults; changing them means editing .issues/config/node-types.json by hand. Both config files are published here as downloads.
• No query language. Filtering is --type and --status; anything richer means the Python API (Node__Service.traverse_graph, find_incoming_links) or grep.
• No .issues DSL command. The DSL is parsed by the core library through Graph__Repository.issues_files_* and has no CLI surface at all — which is part of why nobody has found it.