CLI Module

This module provides command-line argument parsing, flag validation, and usage display for the root script.

Module Overview

• Purpose: Provide command-line argument parsing, flag validation, and usage display for the root script.
• Primary modules:
  • src/lib/cli/help.sh: usage information display
  • src/lib/cli/parser.sh: command-line argument parsing and global variable initialization
  • src/lib/cli/validator.sh: flag validation, mutual exclusivity checks, and compatibility rules

Dependencies

• src/lib/utils/core.sh: die()
• src/lib/logging/logger.sh: log()
• src/lib/cli/help.sh: usage()

Public API

usage()

Display comprehensive help text including all flags, required environment variables, configuration file format, examples, and mutual exclusivity notes.

parse_arguments()

Process all command-line arguments from $@ and set global flag variables. Initializes all flag variables with defaults before parsing, processes flags with values, calls usage() and exits for -h|--help, calls die() for unknown options.

validate_flags()

Validate CLI flags and enforce mutual exclusivity rules and compatibility constraints. Validates mode mutual exclusivity, numeric values, and flag combinations.

Flag Reference Table

Flag	Variable	Default	Purpose
-v, --verbose	VERBOSE	0	Print SQL before sending
-d, --dry-run	DRY_RUN	0	Skip API call, show what would execute
--drop	DROP_FIRST	0	Prepend DROP TABLE statement
-fs, --full-sync	FULL_SYNC	1	Sync both schema and data (default)
-so, --schema-only	SCHEMA_ONLY_OVERRIDE	0	Sync schema only (skip data)
-do, --data-only	DATA_ONLY	0	Sync data only (skip schema)
-i, --incremental	INCREMENTAL	0	Sync only modified notes since last sync
-n, --note-id <id>	NOTE_ID	""	Sync single note by ZUNIQUEIDENTIFIER
--batch-size N	BATCH_SIZE	100	Data sync batch size (rows per batch)
--limit N	LIMIT_ROWS	""	Sync only first N rows
--offset N	OFFSET_ROWS	0	Skip first N rows
--force-overwrite	FORCE_OVERWRITE	0	Delete existing rows before inserting
--debug	DEBUG_LOG	0	Enable verbose DEBUG logging
-h, --help	N/A	N/A	Show usage and exit

Validation Rules

Mutual Exclusivity Rules

1. Mode flags (only one may be set):

   • --data-only and --full-sync are mutually exclusive
   • --data-only and --schema-only are mutually exclusive
   • --full-sync and --schema-only are mutually exclusive

2. Selection flags:

   • --incremental and --note-id are mutually exclusive

Compatibility Constraints

1. Selection flags require data sync:

   • --incremental / --note-id require data sync (incompatible with --schema-only)

2. Incremental mode constraints:

   • --incremental is incompatible with --limit / --offset

3. Single-note mode constraints:

   • --note-id is incompatible with --limit / --offset / --batch-size
   • --note-id automatically sets BATCH_SIZE=1

Integration Pattern

Recommended usage order in bearflare.sh:

1. Source CLI modules (after utils, logging, and config modules)
2. Parse arguments: parse_arguments "$@"
3. Validate flags: validate_flags
4. Proceed with script execution using validated global variables

Navigation

• Architecture Overview - High-level architecture
• Modular Architecture - Module hierarchy and dependencies
• Config Module - Configuration management
• Logging Module - Logging system
• Sync Module - Sync orchestration