API Reference / cli /

setup.py

Setup Command - Interactive wizard to connect TuiML to AI agents.

Classes

C

class cli.setup.C

ANSI color codes.

Functions

Func

banner

Line 33
banner() -> None

Print the setup wizard's title banner.

Func

info

Line 41
info(msg: str) -> None

Print a dimmed informational line.

Parameters

msg
str
Message to display.
Func

success

Line 52
success(msg: str) -> None

Print a green check-marked success line.

Parameters

msg
str
Message to display.
Func

warn

Line 63
warn(msg: str) -> None

Print a yellow warning line.

Parameters

msg
str
Message to display.
Func

error

Line 74
error(msg: str) -> None

Print a red error line.

Parameters

msg
str
Message to display.
Func

section

Line 85
section(title: str) -> None

Print a bold section heading preceded by a blank line.

Parameters

title
str
Heading text.
Func

confirm

Line 97
confirm(prompt: str, default: bool=True, assume_yes: bool=False) -> bool

Ask the user a yes/no question, unless answering has been pre-empted.

Parameters

prompt
str
Question to put to the user.
default
bool = True
Answer used when the user just presses Enter.
assume_yes
bool = False
If True, return True immediately without prompting.

Returns

answer
bool
The user's answer, or True when assume_yes is set.
Func

client_specs

Line 229
client_specs() -> list[dict]

Return the spec for every AI client TuiML knows how to wire up.

Returns

specs
list of dict
One spec per client, each with at least id, name, detect, and kind keys, plus config, key, or skills_dir depending on the kind.
Func

detect_clients

Line 468
detect_clients() -> list[dict]

Return the specs of clients that appear to be installed.

A client counts as installed if its detect path exists, if its detect_glob pattern matches a versioned install directory, or if its detect_command is on PATH.

Returns

detected
list of dict
The subset of client_specs found on this machine.
Func

backup_file

Line 508
backup_file(path: Path) -> Optional[Path]

Copy a file alongside itself with a timestamped .bak suffix.

Parameters

path
Path
File to back up.

Returns

backup
Path or None
Path of the backup copy, or None if path did not exist.
Func

write_json_mcp

Line 586
write_json_mcp(config_path: Path, key: str, server_name: str, command: str, entry: Optional[dict]=None) -> tuple[bool, str]

Write an MCP server entry into a JSON config file.

The config file and its parent directories are created if missing, and an existing file is backed up before being rewritten. Idempotent: an entry that already matches what we would write is left untouched.

Parameters

config_path
Path
JSON config file to write.
key
str
Key holding the server map, dotted for nesting, e.g. 'mcp.servers'.
server_name
str
Name to register the server under.
command
str
Executable the client should launch.
entry
dict
Extra fields merged into the server entry alongside command, for clients that require them, e.g. VS Code's {"type": "stdio"}.

Returns

changed
bool
True if the file was modified.
reason
str
Short human-readable description of what happened.
Func

configure_openclaw

Line 668
configure_openclaw(spec: dict) -> tuple[bool, str]

Register TuiML with OpenClaw, preferring its own CLI.

Uses openclaw mcp set when the executable is on PATH, and falls back to editing the JSON config directly if that command is missing or fails.

Parameters

spec
dict
Client spec, providing config and key.

Returns

changed
bool
True if the client configuration was modified.
reason
str
Short human-readable description of what happened.
Func

write_opencode_mcp

Line 708
write_opencode_mcp(config_path: Path, server_name: str, command: str) -> tuple[bool, str]

Write an MCP entry into OpenCode's opencode.json.

OpenCode's schema places servers under a top-level "mcp" key with the shape {"mcp": {"": {"type": "local", "command": [""], "enabled": true}}}. The file is backed up before being rewritten.

Parameters

config_path
Path
Path to opencode.json.
server_name
str
Name to register the server under.
command
str
Executable OpenCode should launch.

Returns

changed
bool
True if the file was modified.
reason
str
Short human-readable description of what happened.
Func

write_toml_mcp

Line 755
write_toml_mcp(config_path: Path, server_name: str, command: str) -> tuple[bool, str]

Append an [mcp_servers.<name>] section to a TOML config.

Follows the OpenAI Codex CLI layout. Idempotent: if the section already exists with the same command, nothing changes; otherwise any prior block for that server is replaced and the file is backed up first.

Parameters

config_path
Path
TOML config file to write.
server_name
str
Name to register the server under.
command
str
Executable the client should launch.

Returns

changed
bool
True if the file was modified.
reason
str
Short human-readable description of what happened.
Func

install_skill_file

Line 805
install_skill_file(skills_dir: Path) -> tuple[bool, str]

Copy the bundled skill (SKILL.md plus its reference and workflow files) into a coding agent's skills directory.

The tree is written under /tuiml/. An existing SKILL.md with different contents is backed up before being overwritten; other files are overwritten in place.

Parameters

skills_dir
Path
The agent's skills directory.

Returns

changed
bool
True if any skill file was written.
reason
str
Short human-readable description of what happened.
Func

print_yaml_instructions

Line 850
print_yaml_instructions(spec: dict) -> tuple[bool, str]

Print the YAML snippet the user must add by hand (Goose and similar).

YAML configs are not edited automatically, to avoid destroying comments and formatting.

Parameters

spec
dict
Client spec, providing config.

Returns

changed
bool
Always False; nothing is written.
reason
str
Note explaining that this is a manual step.
Func

print_instructions

Line 881
print_instructions(spec: dict) -> tuple[bool, str]

Print client-specific setup instructions without editing any config.

Used for clients that cannot be safely auto-wired from the host, e.g. NemoClaw, whose OpenClaw config lives inside a Docker sandbox.

Parameters

spec
dict
Client spec, providing instructions.

Returns

changed
bool
Always False; nothing is written.
reason
str
Note explaining that this is a manual step.
Func

configure

Line 909
configure(spec: dict) -> tuple[bool, str]

Wire TuiML into one client, dispatching on the spec's kind.

Parameters

spec
dict
Client spec from client_specs.

Returns

changed
bool
True if the client configuration was modified.
reason
str
Short human-readable description of what happened.
Func

describe_target

Line 948
describe_target(spec: dict) -> str

Return the path this client's wiring will be written to, for display.

Parameters

spec
dict
Client spec from client_specs.

Returns

target
str
The skills directory for skill-based clients, otherwise the config file path.
Func

resolve_client_ids

Line 982
resolve_client_ids(clients: tuple[str, Ellipsis]) -> tuple[list[str], list[str]]

Map user-supplied --client slugs onto canonical spec IDs.

Parameters

clients
tuple of str
Slugs passed on the command line.

Returns

resolved
list of str
Canonical spec IDs, with aliases translated.
unknown
list of str
Slugs that match neither an ID nor an alias.
Func

prompt_mode

Line 1007
prompt_mode(default: str='auto') -> str

Ask whether to configure all detected clients at once or one by one.

Parameters

default
str = "auto"
Choice used when the user just presses Enter.

Returns

mode
{"auto", "manual", "quit"}
The selected mode.
Command

tuiml setup

Line 1043
tuiml setup [OPTIONS]

Connect TuiML to your AI agents.

Detects installed clients and wires them up: appends an MCP server entry for MCP clients, copies the SKILL.md file for skill-based agents, or prints manual instructions for YAML and unsupported configs. Every config file is backed up before it is modified, and re-running is safe: a client that is already wired correctly is left alone.

By default the wizard asks whether to configure every detected client at once (Auto) or one by one (Manual). Pass -y / --yes to skip the menu and go straight to Auto, or --manual to go straight to Manual. Undo everything with tuiml uninstall.

Run the interactive wizard:

bash 
$ tuiml setup

See which clients are detected, without changing anything:

bash 
$ tuiml setup --list

Wire up every detected client without prompting:

bash 
$ tuiml setup --yes

Configure only specific clients:

bash 
$ tuiml setup --client claude-code --client cursor

Options

--yes, -y
flag
Auto mode: configure every detected client without prompting.
--manual
flag
Manual mode: ask before configuring each client, skipping the Auto/Manual menu.
--list
flag
List the detected clients and their config paths, then exit without changing anything.
--client
repeatable
Configure only this client, by ID. Repeatable. Run 'tuiml setup --list' to see valid IDs.