Core Functions¶

Core functionality provided by the fscm module.

Command Execution¶

run¶

Execute a shell command.

fscm.run(cmd, check=True, sudo=False, quiet=False, **kwargs)

Parameters:

Name	Type	Default	Description
`cmd`	str	required	Command to execute
`check`	bool	True	Raise on non-zero exit
`sudo`	bool	False	Run with sudo
`quiet`	bool	False	Suppress output
`destructive`	bool	True	Track in changelist
`env`	dict	None	Environment variables
`cwd`	str	None	Working directory
`stdin`	str	None	Input to send
`timeout`	int	None	Timeout in seconds

Returns: RunReturn object

Example:

result = fscm.run("ls -la")
print(result.stdout)

fscm.run("systemctl restart nginx", sudo=True)

run_ro¶

Execute a read-only (non-destructive) command quietly.

fscm.run_ro(cmd, **kwargs)

Equivalent to run(cmd, quiet=True, destructive=False).

Example:

result = fscm.run_ro("cat /etc/hostname")
hostname = result.stdout.strip()

getstdout¶

Execute a command and return stdout as a string.

fscm.getstdout(cmd, **kwargs) -> str

Example:

hostname = fscm.getstdout("hostname")

fails¶

Check if a command fails (returns non-zero).

fscm.fails(cmd) -> bool

Example:

if fscm.fails("systemctl is-active nginx"):
    print("nginx is not running")

runmany¶

Execute multiple commands.

fscm.runmany(cmds, **kwargs)

Parameters:

Name	Type	Description
`cmds`	str or list	Commands (newline-separated string or list)

Example:

fscm.runmany("""
    apt-get update
    apt-get install -y nginx
    systemctl enable nginx
""", sudo=True)

File Operations¶

file¶

Create or update a file.

fscm.file(path, content, mode=None, owner=None, sudo=False, encoding='utf-8')

Parameters:

Name	Type	Default	Description
`path`	str/Path	required	File path
`content`	str/bytes/Path	required	File contents
`mode`	str	None	Permissions (e.g., "0644")
`owner`	str	None	Owner (e.g., "root:root")
`sudo`	bool	False	Use sudo for writing
`encoding`	str	"utf-8"	Text encoding

Returns: ChangeList

Example:

fscm.file("/etc/myapp.conf", "setting=value\n", mode="0644")

mkdir¶

Create a directory.

fscm.mkdir(path, mode=None, owner=None, sudo=False)

Creates parent directories as needed.

Example:

fscm.mkdir("/var/www/myapp/static", mode="0755", owner="www-data:www-data")

chmod¶

Change file permissions.

fscm.chmod(path, mode, flags="", sudo=False)

Example:

fscm.chmod("/var/www/myapp", "0755", flags="-R")

chown¶

Change file ownership.

fscm.chown(path, owner, flags="", sudo=False)

Example:

fscm.chown("/var/www/myapp", "www-data:www-data", flags="-R")

lineinfile¶

Ensure a line exists in a file.

fscm.lineinfile(path, line=None, regexp=None, state="present", sudo=False)

Parameters:

Name	Type	Default	Description
`path`	str	required	File path
`line`	str	None	Line content to ensure
`regexp`	str	None	Pattern to match
`state`	str	"present"	"present" or "absent"

Example:

fscm.lineinfile(
    "/etc/ssh/sshd_config",
    line="PermitRootLogin no",
    regexp=r"^#?PermitRootLogin"
)

make_executable¶

Make a file executable.

fscm.make_executable(path, sudo=False)

backup_file¶

Create a backup of a file.

fscm.backup_file(path, sudo=False) -> Path | None

Returns the backup path or None if backup disabled.

Templates¶

template¶

Render a Jinja2 template.

fscm.template(template_path, **variables) -> str

Example:

config = fscm.template(
    "templates/nginx.conf.j2",
    domain="example.com",
    port=80
)
fscm.file("/etc/nginx/nginx.conf", config)

System Object¶

s¶

The global system object provides OS-specific operations.

fscm.s  # Debian, Arch, or MacOS instance

s.pkgs_install¶

Install packages using the system package manager.

fscm.s.pkgs_install(*packages, sudo=True)

Example:

fscm.s.pkgs_install("nginx", "certbot", "python3")

s.pkg_is_installed¶

Check if a package is installed.

fscm.s.pkg_is_installed(name) -> bool

s.pkg_get_installed_version¶

Get the installed version of a package.

fscm.s.pkg_get_installed_version(name) -> str | None

Utility Functions¶

detect_system¶

Detect the current operating system.

fscm.detect_system() -> UnixSystem

Returns a Debian, Arch, or MacOS instance.

hostname¶

Get the system hostname.

fscm.hostname() -> str

this_file_path¶

Get the path of the calling script.

fscm.this_file_path() -> Path

this_dir_path¶

Get the directory of the calling script.

fscm.this_dir_path() -> Path

p¶

Create a PathHelper for convenient path operations.

fscm.p(path) -> PathHelper

Example:

path = fscm.p("/var/www/myapp")
path.mkdir().chmod("0755").chown("www-data")

get_secrets¶

Load secrets from pass password manager.

fscm.get_secrets(path) -> dict

download_and_check_sha¶

Download a file and verify its SHA256 checksum.

fscm.download_and_check_sha(url, dest, sha256)

RunReturn¶

Object returned by run().

Properties¶

Property	Type	Description
`ok`	bool	True if exit code is 0
`returncode`	int	Exit code
`stdout`	str/bytes	Standard output
`stderr`	str/bytes	Standard error

Methods¶

assert_ok¶

Raise an exception if the command failed.

result.assert_ok()

to_change¶

Convert to a CmdRun change object.

change = result.to_change