Advanced Usage - edgeof8/tIRC GitHub Wiki

This page delves into more advanced configuration options, operational modes, and features of tIRC, allowing power users to tailor the client to their specific needs.

tIRC uses config/tirc_config.ini for its primary configuration. While a basic setup is covered in the Quick Start guide, this file offers many more options for fine-tuning. The README.md highlights several key sections:

• [Server.YourServerName]: Define multiple server profiles.

  • Connection: address, port, ssl (true/false), server_password (optional).
  • Identity: nick, username (optional, defaults to nick), realname (optional, defaults to nick).
  • Authentication: nickserv_password (optional), sasl_username, sasl_password (for SASL PLAIN).
  • Security: verify_ssl_cert (true/false).
  • Behavior: auto_connect (true for one server to connect on startup), channels (comma-separated list of channels to auto-join).
  • IRCv3: desired_caps (optional, comma-separated list of IRCv3 capabilities to request).

• [UI]:

  • message_history_lines: Number of lines to keep in message buffers.
  • headless_message_history_lines: History lines for headless mode.
  • colorscheme: Defines the color scheme (e.g., dark, light). (Refer to Style Guide if color schemes are detailed there).

• [Logging]:

  • log_enabled: Master switch for logging.
  • log_file: Path to the main application log (e.g., logs/tirc_core.log).
  • log_level: Logging verbosity (e.g., INFO, DEBUG).
  • Rotation settings (e.g., log_max_bytes, log_backup_count).
  • channel_log_enabled: Enable/disable per-channel logging.
  • (See Debugging And Logging for more).

• [Features]:

  • enable_trigger_system: Toggle the /on command trigger system.

• [Scripts]:

  • disabled_scripts: Comma-separated list of script module names to prevent from loading.

• [IgnoreList]: This section is typically managed by the /ignore, /unignore, and /listignores commands and stores persistent ignore patterns.

• [DCC]: Extensive settings for Direct Client-to-Client functionality.

  • enabled: Master switch for DCC.
  • download_dir: Default directory for received files.
  • max_file_size: Maximum allowed file size for transfers.
  • auto_accept: Automatically accept incoming DCC SEND offers.
  • blocked_extensions: Comma-separated list of file extensions to block.
  • port_range_start, port_range_end: Port range for listening sockets.
  • timeout: General timeout for DCC connections/transfers.
  • passive_token_timeout: Timeout for passive DCC offer tokens.
  • checksum_verify, checksum_algorithm: For file integrity checking.
  • bandwidth_limit_send_kbps, bandwidth_limit_recv_kbps: Bandwidth throttling (0 for unlimited).
  • resume_enabled: Allow resuming interrupted transfers.
  • dcc_advertised_ip: Optional manual IP for NAT traversal.
  • cleanup_enabled, cleanup_interval_seconds, transfer_max_age_seconds: For managing old transfer records.
  • DCC logging settings.
  • (For more on DCC, see DCC Support).

You can manage some configuration settings directly within tIRC:

• /set [<section.key> [<value>]]: View or modify settings.
• /rehash: Reloads the configuration from tirc_config.ini.
• /save: Saves the current (potentially modified) client configuration back to tirc_config.ini.

When launching tIRC, you can override certain settings or specify connection parameters directly. These typically create a temporary "CommandLine" server configuration. The README.md mentions:

python tirc.py [--server <server>] [--port <port>] [--nick <nick>] [--channel <#channel>] [--ssl] [--password <server_pass>] [--nickserv-password <pass>] [--headless] [--disable-script <script_name>]

This allows for quick connections without editing the configuration file or for scripting tIRC's launch.

tIRC can run without its terminal UI, which is ideal for bots, automated testing, or AI integrations.

• Activation: Use the --headless flag when launching:

  python tirc.py --headless --connect irc.libera.chat

• Functionality: In headless mode:
  • The core logic, including network handling, event management, and state management, runs as usual.
  • The scripting system (ScriptManager, ScriptAPIHandler) is fully functional.
  • The trigger system (/on command functionality) operates normally.
  • All operations are managed by the asyncio event loop.
• Use Cases:
  • Running automated IRC bots.
  • Integrating tIRC's IRC capabilities into other applications.
  • Performing automated tests of client features and scripts (see scripts/test_headless.py for examples).

Beyond basic commands, tIRC's command system supports:

• Aliases: Many commands have shorter aliases (e.g., /j for /join). Check /help <command>.
• Context Awareness: Some commands operate on the currently active window/context by default.
• Raw Commands: The /raw <irc command> (or /quote) command allows sending any raw line directly to the server, useful for experienced users or for accessing server features not directly supported by a client command.
• Refer to the Command System page for a more detailed overview of command structure and capabilities.

tIRC's Python scripting system is a powerful way to extend its functionality.

• Write custom scripts to automate tasks, add new commands, or react to IRC events in unique ways.
• Scripts have access to a rich ScriptAPIHandler for interacting with the client.
• For detailed information on writing scripts, see the Scripting page and the Script API Reference.

Direct Client-to-Client (DCC) allows for direct file transfers and chats between users.

• tIRC supports DCC SEND and DCC GET, including passive (reverse) offers.
• Configure DCC behavior extensively via the [DCC] section in tirc_config.ini.
• Use commands like /dcc send, /dcc get, /dcc list, etc.
• For a full guide on DCC features and commands, refer to DCC Support.

tIRC's new IPC feature allows external processes, such as shell scripts or other programs, to send commands to a running tIRC instance. This enables powerful automation and remote control capabilities.

• How it works: The main tIRC instance opens a local TCP socket (default port 61234). When you use the --send-raw command-line argument, a new, temporary tIRC process acts as a client, connects to this socket, sends the specified command, and then exits. The running tIRC instance receives and processes this command as if it were typed directly into the client.

• Command-line usage:

  # In one terminal, start tIRC:
  python tirc.py
  
  # In a second terminal, send a command to the running instance:
  python tirc.py --send-raw "/msg #yourchannel Hello from a script!"

• Benefits:

  • Scripting: Automate common IRC tasks or integrate tIRC into larger workflows.
  • Remote Control: Send commands to a headless tIRC instance running on a server.
  • Non-interactive use: Execute single commands without starting a full UI session.

• Configuration: The IPC port can be configured in config/tirc_config.ini under the [IPC] section.