dotctl 1.0.3

A powerful CLI tool to profile your OS by saving, applying, exporting, and importing system configurations as named profiles. Designed to manage dot files and service configurations in a centralized Git repository (local or remote), dotctl enables seamless system replication across machines. Supports pre/post hook scripts, making it ideal for setting up servers or desktops with consistent environments.

DotCtl

dotctl is a powerful CLI tool to manage, save, apply, export, and import system configurations as named profiles.
It helps centralize dotfiles and service configurations in Git repositories for seamless replication across systems.

Designed for developers and sysadmins, it supports pre/post hook scripts and is ideal for setting up consistent environments across desktops and servers.

---

📚 Table of Contents

• DotCtl
  • 📚 Table of Contents
  • 🚀 Features
  • 🔧 Installation
  • 📘 Usage
  • 🛠️ Commands
    • 📁 init
    • 💾 save
    • 📋 list / ls
    • 🔀 switch / sw
    • 🆕 create / new
    • ❌ remove / rm / delete / del
    • 🧪 apply
    • 📤 export
    • 📥 import
    • 🔥 wipe
  • 🧑‍💻 Development & Publishing
    • Setup Development Environment
    • Build the Package
    • Publish to TestPyPI
    • Publish to PyPI
  • 🙋 Contact

---

🚀 Features

• 📦 Profile Management — Create, switch, save, remove, and apply system profiles.
• 🌀 Pre/Post Hooks — Run scripts before or after activating a profile (e.g., install packages, restart services).
• 🔄 Git Integration — Sync profiles with local or remote Git repositories.
• 📁 Portable Configs — Export/import profiles using .dtsv files for easy backups and sharing.
• ⚙️ Custom Configs — Define tracking rules via dotctl.yaml.

---

🔧 Installation

pip install dotctl

---

📘 Usage

dotctl [OPTIONS] <COMMAND> [ARGS]

Run dotctl -h for global help or dotctl <COMMAND> -h for command-specific help.

---

🛠️ Commands

📁 init

Initialize a new profile.

dotctl init [-h] [-u <git-url>] [-p <profile>] [-c <config-path>] [-e <env>]

Examples:

dotctl init -e kde
dotctl init -u https://github.com/user880/dots.git -p mydesktop
dotctl init -c ./my_custom_config.yaml

Options:

• -e, --env – Target environment (e.g., kde, gnome, server).
• -u, --url – Git URL to clone profile from.
• -p, --profile – Activate this profile after init.
• -c, --config – Path to custom YAML config.

---

💾 save

Save current system state to the active profile.

dotctl save [-h] [-p <password>] [--skip-sudo] [profile]

Examples:

dotctl save
dotctl save my_web_server --skip-sudo
dotctl save my_web_server -p mYsecretp@ssw0rd

Options:

• --skip-sudo – Ignore restricted resources.
• -p, --password – Password for restricted resources.

---

📋 list / ls

List all profiles.

dotctl list [-h] [--details] [--fetch]

Examples:

dotctl list
dotctl list --details
dotctl list --fetch

Options:

• --details – Show extended info.
• --fetch – Refresh remote data.

---

🔀 switch / sw

Switch to another profile.

dotctl switch [-h] [--fetch] [profile]

Examples:

dotctl switch MyProfile
dotctl sw MyProfile --fetch

Options:

• --fetch – Refresh profile info before switching.

---

🆕 create / new

Create a new, empty profile.

dotctl create [-h] [--fetch] <profile>

Examples:

dotctl create myserver
dotctl new myserver --fetch

Options:

• --fetch – Sync with remote before creating.

---

❌ remove / rm / delete / del

Remove a profile locally and/or remotely.

dotctl remove [-h] [-y] [--fetch] <profile>

Examples:

dotctl rm MyProfile
dotctl del MyProfile --fetch
dotctl del MyProfile -y

Options:

• --fetch – Refresh data before removal.
• -y, --no-confirm – Skip confirmation prompt.

---

🧪 apply

Apply a saved profile.

dotctl apply [-h] [-p <password>] [--skip-sudo] [--skip-hooks] [--skip-pre-hooks] [--skip-post-hooks] [--ignore-hook-errors] [profile]

Examples:

dotctl apply
dotctl apply mydesktop --skip-hooks
dotctl apply MyProfile --skip-pre-hooks --ignore-hook-errors

Options:

• --skip-sudo – Ignore restricted resources.
• --skip-hooks – Skip all hooks.
• --skip-pre-hooks – Skip only pre-hooks.
• --skip-post-hooks – Skip only post-hooks.
• --ignore-hook-errors – Don’t abort if hooks fail.
• -p, --password – Password for restricted actions.

---

📤 export

Export a profile to .dtsv.

dotctl export [-h] [-p <password>] [--skip-sudo] [profile]

Examples:

dotctl export
dotctl export my_web_server --skip-sudo
dotctl export my_web_server -p mYsecretp@ssw0rd

Options:

• --skip-sudo, -p same as above.

---

📥 import

Import a .dtsv profile.

dotctl import [-h] [-p <password>] [--skip-sudo] <file.dtsv>

Examples:

dotctl import my_web_server.dtsv
dotctl import /data/backup/web.dtsv --skip-sudo

Options:

• --skip-sudo, -p same as above.

---

🔥 wipe

Remove all local profiles.

dotctl wipe [-h] [-y]

Examples:

dotctl wipe
dotctl wipe -y

Options:

• -y, --no-confirm – Do not prompt before wiping.

---

🧑‍💻 Development & Publishing

Setup Development Environment

python -m venv venv
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows

pip install -r requirements.txt

Build the Package

python -m build

Publish to TestPyPI

twine upload --repository testpypi dist/*

Publish to PyPI

twine upload --repository pypi dist/*

---

🙋 Contact

• Maintainer: Pankaj Jackson
• Support: Open an Issue