Setup Wizard¶

ubconnect wizard builds (or updates) a ubproject.toml by walking you through each connector configuration field. It is the quickest way to a valid configuration without reading the connector reference pages: every field is introduced with its description, whether it is required, and its default.

Running the wizard¶

Pass --connector to choose which connector to configure:

$ ubconnect wizard --connector github

The wizard groups its prompts into the connector’s configuration sections. Each section opens with a header and a one-line explanation, for example:

[1/2] GitHub issue import
Fetch issues from a repository and convert them into Sphinx-Needs.

Every field is then prompted individually. The prompt shows the field description, marks the field (required) or (optional), and — for optional fields — states the default that applies if you press Enter:

Repository to import issues from, in 'owner/name' form.
repo (required): useblocks/ubconnect

Prefix prepended to every generated need ID.
id_prefix (optional, default: GH_):

Press Enter on an optional field to accept its default.

Editing an existing configuration¶

When the --output file already exists, the wizard edits it in place. Only the sections owned by the selected connector are replaced; every other table — including comments, [tool.*] tables, and hand-written settings — is preserved. Running the wizard again to adjust a single value is therefore safe.

To replace the whole file instead, pass --force. A --force overwrite first copies the previous file to <output>.bak.

Non-interactive use¶

The wizard can run without prompts, which is useful in scripts and CI:

--answers <file> supplies field values from a TOML or JSON file. Any field present in the answers file is not prompted for.
--no-prompt disables prompting entirely. Combined with --answers it generates a configuration headlessly; a required field that has no answer makes the wizard exit with a non-zero code rather than blocking on input.
--print-config writes the rendered TOML to standard output instead of to a file, so the result can be reviewed or piped elsewhere.

$ ubconnect wizard --connector github --answers answers.toml --no-prompt

Options¶

Option	Description
`--connector`	Connector to configure (for example `github`).
`--output` / `-o`	Path to write the configuration to. Defaults to `ubproject.toml`.
`--answers`	TOML or JSON file supplying field values to skip prompts.
`--no-prompt`	Fail instead of prompting for any missing field.
`--force`	Overwrite the whole `--output` file instead of merging in place.
`--print-config`	Print the rendered TOML to standard output instead of writing it.

Exit codes¶

Code	Meaning
`0`	Success.
`1`	Generic wizard error (for example a detection failure or a malformed existing configuration).
`2`	A required field had no answer under `--no-prompt`.
`3`	Validation of the collected answers failed.
`4`	The answers file contains a key with no matching connector subcommand.
`5`	A `<output>.bak` file already exists; remove or rename it before re-running with `--force`.