CLI Surface Screens — Actual CLI Screens and Errors

Rendered from actual-cli-screens.md. Do not edit screens directly — change the spec and re-render.

Legend

S|
line written to stdout — the command result; what scripts pipe to other tools
E|
line written to stderr — progress, diagnostics, errors; not a stability contract
[exit N]
process exit code: 0 = success, >0 = failure (specific codes per the spec's exit-code map)
< user types: foo >
interactive input typed by the user at a prompt
E|  Hint: …
indented advice line following an error — present only when the project documents a hint system
⚠ design flag
amber banner under the exit line — flags a screen worth design review

V1: Discover root help

$ gcm S| Manage cloned git repositories S| S| Usage: S| gcm [command] S| S| Available Commands: S| clone Clone a repository into its derived path S| completion Generate the autocompletion script for the specified shell S| config Manage gcm configuration S| help Help about any command S| shell-init Print shell integration for changing directory after clone S| status Show repository status under the clone root S| S| Flags: S| -h, --help help for gcm S| S| Use "gcm [command] --help" for more information about a command.
[exit 0]

V2: Inspect command help

$ gcm status --help S| Show repository status under the clone root S| S| Usage: S| gcm status [flags] S| S| Flags: S| -h, --help help for status S| --no-fetch Use local git state without fetching remotes first S| --non-default Show only repositories on non-default branches
[exit 0]
$ gcm shell-init --help S| Print shell integration for changing directory after clone S| S| Usage: S| gcm shell-init [bash|zsh|fish] [flags] S| S| Flags: S| -h, --help help for shell-init S| --install Install shell integration in the detected shell rc file
[exit 0]

V3: Show default configuration

$ gcm config show S| clone_root: ~/src # default
[exit 0]

V4: Set clone root

$ GCM_CONFIG=/tmp/gcm-demo/gcm.yaml gcm config set clone-root /tmp/gcm-demo/src S| Config saved to /tmp/gcm-demo/gcm.yaml
[exit 0]

V5: Show custom configuration

$ GCM_CONFIG=/tmp/gcm-demo/gcm.yaml gcm config show S| clone_root: /tmp/gcm-demo/src
[exit 0]

V6: Clone repository - new clone success

$ GCM_CONFIG=/tmp/gcm-demo/gcm.yaml gcm clone file://localhost/tmp/gcm-demo/remote/aihero.git E| Clone root /tmp/gcm-demo/src does not exist - creating it E| Cloning to /tmp/gcm-demo/src/localhost/tmp/gcm-demo/remote/aihero... E| Done. S| /tmp/gcm-demo/src/localhost/tmp/gcm-demo/remote/aihero
[exit 0]

V7: Clone repository - already present with matching origin

$ GCM_CONFIG=/tmp/gcm-demo/gcm.yaml gcm clone file://localhost/tmp/gcm-demo/remote/aihero.git S| /tmp/gcm-demo/src/localhost/tmp/gcm-demo/remote/aihero
[exit 0]

V8: Status - no repositories

$ GCM_CONFIG=/tmp/gcm-demo/gcm.yaml gcm status --no-fetch S| Repos under /tmp/gcm-demo/src: S| 0 repos — 0 current, 0 behind, 0 non-default-branch
[exit 0]

V9: Status - local scan with non-default dirty repository

$ GCM_CONFIG=/tmp/gcm-demo/gcm.yaml gcm status --no-fetch S| Repos under /tmp/gcm-demo/src: S| localhost/tmp/gcm-demo/remote/aihero feature/docs behind=0 dirty=1 [!main] S| 1 repos — 0 current, 0 behind, 1 non-default-branch S| Tips: gcm status --non-default
[exit 0]

V10: Status - non-default filter

$ GCM_CONFIG=/tmp/gcm-demo/gcm.yaml gcm status --no-fetch --non-default S| Repos under /tmp/gcm-demo/src: S| localhost/tmp/gcm-demo/remote/aihero feature/docs behind=0 dirty=1 [!main] S| 1 repos — 0 current, 0 behind, 1 non-default-branch
[exit 0]

V11: Shell init - print wrapper

$ gcm shell-init zsh S| gcm() { S| if [ "$1" = "clone" ]; then S| local dest S| dest=$(command gcm "$@") S| local command_status=$? S| if [ $command_status -eq 0 ] && [ -n "$dest" ]; then S| cd "$dest" S| fi S| return $command_status S| else S| command gcm "$@" S| fi S| }
[exit 0]

V12: Shell init - install success

$ HOME=/tmp/gcm-demo/home SHELL=/bin/zsh gcm shell-init --install zsh E| Installed in /tmp/gcm-demo/home/.zshrc. Reload your shell or run: source /tmp/gcm-demo/home/.zshrc
[exit 0]
Current implementation writes install status to stderr and no stdout path. Verify whether this is the intended command-result contract.

V13: Shell init - install already present

$ HOME=/tmp/gcm-demo/home SHELL=/bin/zsh gcm shell-init --install zsh E| Already installed in /tmp/gcm-demo/home/.zshrc.
[exit 0]

V14: Clone repository - missing URL

$ gcm clone E| accepts 1 arg(s), received 0
[exit 2]
Actual usage error does not name the missing url argument and does not use the output-spec Error: form.

V15: Clone repository - malformed URL

$ gcm clone not-a-url E| parse repository URL "not-a-url": missing hostname
[exit 1]
Actual runtime error does not use the output-spec Error: form.

V16: Clone repository - destination blocked

$ GCM_CONFIG=/tmp/gcm-demo/gcm.yaml gcm clone https://github.com/example/blocked.git E| cannot clone to /tmp/gcm-demo/src/github.com/example/blocked: destination exists but is not a git repository. Move or remove it first, then run gcm clone again
[exit 1]
Actual runtime error includes remediation in the reason sentence but does not use the output-spec Error: form.

V17: Shell init - unsupported shell

$ gcm shell-init tcsh E| Error: shell "tcsh": unsupported shell
[exit 2]

V18: Unknown command

$ gcm frobnicate E| unknown command "frobnicate" for "gcm"
[exit 2]

V19: Unknown flag

$ gcm status --json E| unknown flag: --json
[exit 2]