cligram.config

Application configuration management.

class cligram.config.ApiConfig(id=0, hash='')

Bases: object

Telegram API credentials.

from_env: bool = False

Indicates if the credentials were loaded from environment variables

hash: str = ''

Telegram API hash string obtained from my.telegram.org/apps

id: int = 0

Telegram API ID obtained from my.telegram.org/apps

property identifier: str

Get unique identifier for the API credentials.

property valid: bool

Check if API credentials are valid.

class cligram.config.AppConfig(delays=<factory>, verbose=False)

Bases: object

Main application behavior configuration.

delays: DelaysConfig

Delay timing configurations

verbose: bool = False

Enable debug logging

class cligram.config.Config(_config_path=PosixPath('/home/docs/.cligram/config.json'), app=<factory>, telegram=<factory>, scan=<factory>, interactive=<factory>, updated=False, overridden=False)

Bases: object

Application configuration root.

app: AppConfig

Application behavior settings

apply_override(override_str)

Apply a configuration override using dot notation.

Parameters:

override_str (str) – Override string in format “path.to.key=value” Examples: “app.verbose=true”, “scan.limit=200”

Raises:

ValueError – If override string is invalid

classmethod from_file(config_path='config.json', overrides=None)

Load configuration from JSON file.

Return type:

Config

classmethod get_config(raise_if_failed=True)

Get application configurations.

Return type:

Optional[Config]

get_nested_value(path, bypass_interceptor=False)

Get a nested configuration value using dot notation.

Parameters:

• path (str) – Dot-separated path to value (e.g., “app.verbose”)

• bypass_interceptor (bool) – Whether to bypass attribute interceptor

Return type:

Any

Returns:

Value at the specified path

Raises:

ValueError – If path is invalid

interactive: InteractiveConfig

Interactive mode settings

overridden: bool = False

Indicates if the configuration was overridden via CLI

path: PathInfo

Application paths.

save(path=None)

Save configuration to JSON file.

scan: ScanConfig

Scanning behavior and timing settings

set_nested_value(path, value, bypass_interceptor=False)

Set a nested configuration value using dot notation.

Parameters:

• path (str) – Dot-separated path to value (e.g., “app.verbose”)

• value (Any) – Value to set

• bypass_interceptor (bool) – Whether to bypass attribute interceptor

Raises:

ValueError – If path is invalid

telegram: TelegramConfig

Telegram client and connection settings

temp: Dict[str, Any]

Temporary in-memory configuration data

to_dict()

Export configuration as dictionary.

Return type:

Dict[str, Any]

updated: bool = False

Indicates if the configuration was updated with new fields

class cligram.config.ConnectionConfig(direct=True, proxies=<factory>)

Bases: object

Connection settings for Telegram client.

direct: bool = True

Whether to allow direct connection

proxies: List[str]

List of proxy URLs to try for connection

class cligram.config.DelayConfig(min=10.0, max=20.0)

Bases: object

Delay interval configuration.

max: float = 20.0

Maximum delay in seconds

min: float = 10.0

Minimum delay in seconds

random()

Generate random delay within configured bounds

Return type:

float

class cligram.config.DelaysConfig(normal=<factory>, long=<factory>)

Bases: object

Delay timing configuration.

long: LongDelayConfig

Long break delay settings

normal: DelayConfig

Normal delay settings

random()

Generate a random delay based on configured normal and long delays.

Returns:

Random delay duration in seconds

Return type:

float

class cligram.config.InteractiveConfig(mode=InteractiveMode.CLIGRAM)

Bases: object

Interactive mode configuration.

mode: InteractiveMode = 'cligram'

The interactive mode to use

class cligram.config.InteractiveMode(*values)

Bases: Enum

Interactive mode options.

CLIGRAM = 'cligram'

Interactive mode with Cligram commands

PYTHON = 'python'

Interactive mode with Python code execution

class cligram.config.LongDelayConfig(min=30.0, max=60.0, chance=0.1)

Bases: DelayConfig

Configuration for long delay periods.

chance: float = 0.1

Probability (0-1) of taking a long delay instead of normal delay

max: float = 60.0

Maximum delay in seconds

min: float = 30.0

Minimum delay in seconds

class cligram.config.MessagesConfig(source='me', limit=20, msg_id=None)

Bases: object

Configuration for message forwarding.

limit: int = 20

Maximum number of messages to be loaded from source

msg_id: Optional[int] = None

Specific message ID to forward (optional)

property randomize: bool

Determine if message selection should be randomized.

source: str = 'me'

Source of messages to forward (‘me’ or channel username)

class cligram.config.PathInfo(config_path, is_global, base_path, data_path, session_path)

Bases: object

base_path: Path

Base directory for storing Cligram data.

config_path: Path

Path to the configuration file.

data_path: Path

Directory for application state (and sessions if not global).

get_sessions()

Get list of session files in the session directory.

Return type:

List[Path]

is_global: bool

Indicates if the configuration placed in the global config path.

session_path: Path

Path to the session files for the current api configuration.

class cligram.config.ScanConfig(messages=<factory>, mode=ScanMode.FULL, targets=<factory>, limit=50, test=False, rapid_save=False)

Bases: object

Configuration for scanning behavior and timing.

limit: int = 50

Maximum number of messages to scan per group

messages: MessagesConfig

Message forwarding settings

mode: ScanMode = 'full'

Operation mode

rapid_save: bool = False

Enable rapid state saving to disk

targets: List[str]

List of target groups to scan (usernames or URLs)

test: bool = False

Test mode without sending messages

class cligram.config.ScanMode(*values)

Bases: Enum

Operation modes for the scanner.

FULL = 'full'

scans and sends messages to targets.

Type:

Full operation mode

HALT = 'halt'

logs in to telegram and shuts down.

Type:

Halt mode

LOGOUT = 'logout'

logs out from the Telegram and deletes the session file.

Type:

Logout mode

RECEIVE = 'receive'

receives and shows new messages.

Type:

Receive mode

SCAN = 'scan'

only scans and stores eligible usernames without sending.

Type:

Scan mode

SEND = 'send'

only sends messages to eligible usernames without scanning.

Type:

Send mode

class cligram.config.StartupConfig(count_unread_messages=True)

Bases: object

Telegram client startup settings.

count_unread_messages: bool = True

Show unread messages count on startup

class cligram.config.TelegramConfig(api=<factory>, connection=<factory>, startup=<factory>, session='default', impersonate=False)

Bases: object

Telegram client settings.

api: ApiConfig

API credentials from my.telegram.org

connection: ConnectionConfig

Connection settings

impersonate: bool = False

Impersonate device info from session metadata

session: str = 'default'

Session file name for persistent authorization

startup: StartupConfig

Startup behavior settings