---

name: cli-and-config description: "Guides labelme CLI startup, GUI session configuration, label and flag sources, YAML Settings, output paths, and display-related recovery." disable-model-invocation: true metadata: disco-role: operating license: GPL 3.0

CLI and Config

Use this route when the task is to launch labelme, choose annotation-session options, configure labels/flags, control saving or navigation, or debug a Config File and GUI startup.

Workflow

1. Confirm Python 3.12+ and install labelme in the target environment.
2. Run labelme --help and labelme --version before opening a GUI.
3. Choose a path (image, Annotation File, or directory), then add only the needed flags. Read references/cli-reference.md for exact behavior.
4. Use --labels and --flags with comma-separated values or a text file; use --label-flags for YAML label-specific Shape Flags.
5. Use --output as a directory for a session, not a .json filename, unless the behavior is intentionally a single target as described in the CLI ref.
6. Use --config <file> for a writable Config File or --config '{...}' for ephemeral session overrides. Inspect a candidate without writing it with scripts/inspect_labelme_config.py.
7. If --validate-label exact is enabled, provide a non-empty label list.
8. If the GUI fails, prove the CLI parser works, then check display/Qt setup; read references/troubleshooting.md.

Config rules that matter

• Defaults live in the shipped Default Config; the user Config File is sparse YAML Overrides, normally ~/.labelmerc.
• GUI Settings apply immediately and preserve comments where possible.
• A CLI override or inline YAML makes that session's settings non-editable; use a file if interactive Settings editing is required.
• YAML 1.2 means true/false are booleans; yes/no/on/off are strings.
• canvas.allow_out_of_bounds_points is opt-in and preserves negative or beyond-image coordinates for partially visible objects.
• Window State (geometry/docks) is separate Qt QSettings state; --reset-config clears that state and is not a substitute for editing YAML Overrides.

References and helper

• Read references/cli-reference.md for flags and output semantics.
• Read references/configuration.md for Settings groups, migration behavior, YAML examples, and validation constraints.
• Read references/troubleshooting.md for install, Qt/display, and malformed config recovery.
• Run scripts/inspect_labelme_config.py --config-yaml '{labels: [cat]}' --show labels to validate an inline mapping without writing a Config File.

Route JSON schema questions to ../annotation-data/SKILL.md, conversion questions to ../dataset-export/SKILL.md, AI model/prompt questions to ../ai-assisted-annotation/SKILL.md, and source/test changes to ../repo-development/SKILL.md.