---
id: TASK-1.2
title: Add command-wide --profile/-p option and wire to commands
status: Done
assignee:
  - codex
created_date: '2026-01-29 15:38'
updated_date: '2026-01-29 16:06'
labels: []
dependencies: []
references:
  - bin/zync
  - lua/zync
  - spec
parent_task_id: TASK-1
---

## Description

<!-- SECTION:DESCRIPTION:BEGIN -->
Introduce a global zync option `--profile`/`-p` that selects one of the profiles defined in the project config and overrides the default selection when provided. This should be parsed at the top level and available to all commands, rather than implemented as a per-command shared option.
<!-- SECTION:DESCRIPTION:END -->

## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Global zync option `-p`/`--profile` is parsed at the top level and available to all commands (not duplicated per-command)
- [x] #2 CLI help/usage text documents the new global option and describes defaulting behavior
- [x] #3 If `--profile` is supplied and the profile is not defined, zync exits with a clear error
- [x] #4 Existing commands continue to work unchanged when no profiles are configured
- [x] #5 Tests cover CLI parsing and profile override behavior
<!-- AC:END -->

## Implementation Plan

<!-- SECTION:PLAN:BEGIN -->
1) Review CLI parsing in `lua/zync/api.lua` and command wiring to confirm how global options are defined today.
2) Add a top-level `--profile/-p` option to the main argparse parser (not per-command).
3) Pass the parsed profile into config initialization so profile selection happens early and applies to all commands.
4) Update CLI help/usage and README to document the global option and defaulting behavior.
5) Add tests for CLI parsing and profile override behavior in `spec/api_spec/commands_spec.lua` or relevant CLI tests.
6) Run `busted` and update task notes/acceptance criteria.
<!-- SECTION:PLAN:END -->

## Implementation Notes

<!-- SECTION:NOTES:BEGIN -->
Added global `--profile/-p` option to top-level parser in `lua/zync/api.lua` and passed it into configurator init.

Configurator now errors when a profile is requested but profiles are not configured (`lua/zync/api/configurator.lua`).

Documented global profile option and default behavior in `README.md`.

Added CLI parse/profile override test in `spec/zync_spec.lua` and stabilized test harness `spec/zync_test.lua` by clearing/restoring `_G.arg`.

Ran `busted` (all 41 specs passing).
<!-- SECTION:NOTES:END -->
