{"id":30064942,"url":"https://github.com/prassamin/prasmoid","last_synced_at":"2025-08-08T05:24:34.432Z","repository":{"id":306709526,"uuid":"1024836150","full_name":"PRASSamin/prasmoid","owner":"PRASSamin","description":"The All in One Development Toolkit for KDE Plasmoids.","archived":false,"fork":false,"pushed_at":"2025-08-05T21:31:26.000Z","size":160,"stargazers_count":18,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-05T22:24:28.336Z","etag":null,"topics":["cli","developer-tools","golang","kde","kde-plasma","linux-desktop","plasma-desktop","plasmoid","qt6"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PRASSamin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-23T10:15:10.000Z","updated_at":"2025-08-05T21:31:30.000Z","dependencies_parsed_at":"2025-07-27T06:34:05.017Z","dependency_job_id":"914eda0a-7a6d-40cf-b98a-099edf5c06c0","html_url":"https://github.com/PRASSamin/prasmoid","commit_stats":null,"previous_names":["prassamin/prasmoid"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/PRASSamin/prasmoid","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PRASSamin%2Fprasmoid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PRASSamin%2Fprasmoid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PRASSamin%2Fprasmoid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PRASSamin%2Fprasmoid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PRASSamin","download_url":"https://codeload.github.com/PRASSamin/prasmoid/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PRASSamin%2Fprasmoid/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269367431,"owners_count":24405394,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-08T02:00:09.200Z","response_time":72,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","developer-tools","golang","kde","kde-plasma","linux-desktop","plasma-desktop","plasmoid","qt6"],"created_at":"2025-08-08T05:24:32.265Z","updated_at":"2025-08-08T05:24:34.413Z","avatar_url":"https://github.com/PRASSamin.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Prasmoid CLI\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"logo.svg\" alt=\"Prasmoid Logo\" width=\"300\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eThe All in One Development Toolkit for KDE Plasmoids\u003c/strong\u003e\n  \u003cbr /\u003e\n  Build, test, and manage your plasmoids with unparalleled ease and efficiency.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/PRASSamin/prasmoid/pulls\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/PR-Welcome-brightgreen\" alt=\"PRs Welcome\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://go.dev/\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/Go-1.24-blue.svg\" alt=\"Go Version\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"./LICENSE\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" alt=\"License\"\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Why Prasmoid?\n\nWhile the core structure of KDE Plasma plasmoids is straightforward, the surrounding development workflow, including setup, building, testing, and deployment often involves repetitive manual steps. **Prasmoid CLI** is designed to abstract away these boring tasks. It's a powerful command-line tool, crafted with Go, that provides a seamless, integrated experience, allowing you to **focus solely on writing your plasmoid's code**.\n\n**Focus on your code, not the boilerplate.** Prasmoid handles the heavy lifting, from project scaffolding and live previews to smart versioning and packaging, allowing you to concentrate on creating amazing plasmoids.\n\nOne of its most revolutionary features is a **built-in, zero-dependency JavaScript runtime**. This allows you to extend the CLI with your own custom commands, automating any workflow imaginable, directly within your project – no Node.js installation required!\n\n## Getting Started\n\n### Installation\n\nPrasmoid is designed for quick and easy installation. Choose your preferred method:\n\n\u003e [!IMPORTANT]\n\u003e The installer script requires jq to be installed for parsing GitHub API responses.\n\u003e Install it via `sudo apt install jq`, `sudo dnf install jq`, `sudo pacman -S jq` depending on your distro.\n\n#### Recommended: Standard Build (Native)\n\n- **Best for**: `Arch`, `Fedora`, `Ubuntu`, `Debian`, and most general-purpose Linux distros.\n- This version is compiled with CGO enabled and links to your system's native libraries for full integration and performance.\n- Might not work on minimal or stripped-down systems without standard dev libraries.\n\n```bash\nsudo curl -sSL https://raw.githubusercontent.com/PRASSamin/prasmoid/main/install | bash -s 1\n```\n\n#### Portable Build (Static)\n\n- **Best for**: `Alpine`, `NixOS`, minimal Docker images, CI/CD environments, or any system without full libc/glibc.\n- Fully statically linked (CGO disabled), built to just run anywhere, even on weird-ass environments where shared libs are missing.\n- Slightly larger binary, but way more portable.\n\n```bash\nsudo curl -sSL https://raw.githubusercontent.com/PRASSamin/prasmoid/main/install | bash -s 2\n```\n\n#### Arch Linux (AUR)\n\n- **Best for**: `Arch`, `Manjaro`, and other Arch-based distros.\n- ***Tested on***: 'Arch Linux' (fully up-to-date as of 2025-08-05)\n\n- Official AUR package\n\n```bash\nyay -S prasmoid\n```\n\n#### Debian (.deb)\n\n- **Best for**: `Debian`, `(K)Ubuntu`, and other Debian derivatives.\n- ***Tested on***: 'Debian testing' (nightly snapshot 2025-08-05), 'Kubuntu 25.04'\n\n- [Official Debian package](https://lorteau.fr/prasmoid/prasmoid_0.0.3-0_amd64.deb)\n\n```bash\nwget https://lorteau.fr/prasmoid/prasmoid_0.0.3-0_amd64.deb \u0026\u0026 sudo dpkg -i prasmoid_0.0.3-0_amd64.deb\n```\n\n#### Fedora (.rpm)\n\n- **Best for**: `Fedora`, `RHEL`, `CentOS` and other Fedora derivatives.\n- ***Tested on***: 'Fedora 42'\n\n- [Official Fedora package](https://lorteau.fr/prasmoid/prasmoid-0.0.3-1.fc42.x86_64.rpm)\n\n```bash\nwget https://lorteau.fr/prasmoid/prasmoid-0.0.3-1.fc42.x86_64.rpm \u0026\u0026 sudo dnf install prasmoid-0.0.3-1.fc42.x86_64.rpm\n```\n\n#### Installation via Go\n\n- **Best for**: `Any system with Go installed`.\n- **_Tested on_**: 'Fedora Linux 42(KDE)'\n\n\u003e [!IMPORTANT]\n\u003e This method requires Go to be installed on your system.\n\n```bash\ngo install github.com/PRASSamin/prasmoid\n```\n\n### Updating Prasmoid\n\nKeep Prasmoid up to date with the latest features and improvements using one of these methods:\n\n#### 1. CLI Method (Recommended)\n\nThe simplest way to update Prasmoid is by using the built-in update command:\n\n```bash\nsudo prasmoid upgrade\n```\n\n\u003e [!TIP]\n\u003e This command is a convenient wrapper around the manual update method. It's designed to be lightweight and efficient, avoiding the need for additional internal update logic that would increase the binary size.\n\n#### 2. Manual Update via Curl\n\nIf you prefer a manual update, you can use curl:\n\n```bash\nsudo curl -sSL https://raw.githubusercontent.com/PRASSamin/prasmoid/main/update | sudo bash -s $(which prasmoid)\n```\n\n#### Go Upgrade\n\n#### Upgrading Go Installations\n\nIf you installed Prasmoid using `go install`, use the following command to upgrade:\n\n```bash\nsudo env \"PATH=$PATH\" prasmoid upgrade\n```\n\n\u003e [!NOTE]\n\u003e You can also use the `Manual Update via Curl` method mentioned above. However, if you want to use the CLI method, you must use the `env \"PATH=$PATH\"` prefix as shown.\n\n\u003e [!WARNING]\n\u003e The `env \"PATH=$PATH\"` is required because `sudo` uses a restricted PATH by default. This ensures the system can locate the Go-installed `prasmoid` binary in your user's Go bin directory.\n\n## Your First Plasmoid Project\n\nCreating a new plasmoid is incredibly simple with `prasmoid init`.\n\n1.  **Run the initialization command:**\n\n    ```bash\n    prasmoid init\n    ```\n\n2.  **Follow the interactive prompts:** Prasmoid will guide you through setting up your project details:\n\n    ```\n    ? Project name: MyAwesomePlasmoid\n    ? Description: A new plasmoid project.\n    ? Choose a license: GPL-3.0+\n    ? Author: Alex Doe\n    ? Author email: alex@example.com\n    ? Plasmoid ID: org.kde.myawesomeplasmoid\n    ? Initialize a git repository? Yes\n    ```\n\n    Once completed, a new project directory will be created with your chosen configuration, ready for development!\n\n## Command Reference\n\nPrasmoid provides a comprehensive set of commands to manage your plasmoid projects.\n\n| Command             | Description                                                             | Usage \u0026 Flags                                                                                                                                 |\n| :------------------ | :---------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------- |\n| `setup`             | Bootstraps the development environment (e.g. installs dependencies).    | `prasmoid setup`                                                                                                                              |\n| `init`              | Initializes a new plasmoid project.                                     | `prasmoid init [-n \u003cname\u003e]` \u003cbr\u003e `-n, --name`: Project name.                                                                                  |\n| `build`             | Packages the project into a `.plasmoid` archive.                        | `prasmoid build [-o \u003coutput_dir\u003e]` \u003cbr\u003e `-o, --output`: Output directory (default: `./build`).                                                |\n| `preview`           | Launches the plasmoid in a live preview window.                         | `prasmoid preview [-w]` \u003cbr\u003e `-w, --watch`: Auto-restart on file changes.                                                                     |\n| `format`            | Formats all `.qml` files in the `contents` directory using `qmlformat`. | `prasmoid format [-d \u003cdir\u003e] [-w]` \u003cbr\u003e `-d, --dir`: Directory to format (default: `./contents`). \u003cbr\u003e `-w, --watch`: Watch and auto-format.   |\n| `link`              | Symlinks the project to KDE’s development plasmoids directory.          | `prasmoid link [-w]` \u003cbr\u003e `-w, --where`: Show the linked path only.                                                                           |\n| `unlink`            | Removes the symlink created by `link`.                                  | `prasmoid unlink`                                                                                                                             |\n| `install`           | Installs the plasmoid system-wide for production use.                   | `prasmoid install`                                                                                                                            |\n| `uninstall`         | Uninstalls the plasmoid from the system.                                | `prasmoid uninstall`                                                                                                                          |\n| `changeset`         | Manages versioning and changelogs.                                      | See subcommands below.                                                                                                                        |\n| `changeset add`     | Creates a new changeset with version bump and summary.                  | `prasmoid changeset add [-b \u003ctype\u003e] [-s \u003csummary\u003e]` \u003cbr\u003e `-b, --bump`: `patch`, `minor`, or `major`. \u003cbr\u003e `-s, --summary`: Changelog summary. |\n| `changeset apply`   | Applies pending changesets to `metadata.json` and `CHANGELOG.md`.       | `prasmoid changeset apply`                                                                                                                    |\n| `commands`          | Manages custom JavaScript CLI commands.                                 | See subcommands below.                                                                                                                        |\n| `commands add`      | Adds a new custom JS command in `.prasmoid/commands/`.                  | `prasmoid commands add [-n \u003cname\u003e]` \u003cbr\u003e `-n, --name`: Command name.                                                                          |\n| `commands remove`   | Removes a custom command.                                               | `prasmoid commands remove [-n \u003cname\u003e]` \u003cbr\u003e `-n, --name`: Command name.                                                                       |\n| `i18n`              | Handles internationalization tasks.                                     | See subcommands below.                                                                                                                        |\n| `i18n extract`      | Extracts strings for translation from metadata and QML files.           | `prasmoid i18n extract` \u003cbr\u003e `--no-po`: Skip `.po` generation.                                                                                |\n| `i18n compile`      | Compiles `.po` files into `.mo` files for use in plasmoids.             | `prasmoid i18n compile` \u003cbr\u003e `-s, --silent`: Suppress output. \u003cbr\u003e `--restart`: Restart plasmashell after compiling.                          |\n| `i18n locales`      | Manages supported locales.                                              | See subcommands below.                                                                                                                        |\n| `i18n locales edit` | Launches locale selector to edit supported locales.                     | `prasmoid i18n locales edit`                                                                                                                  |\n| `regen`             | Regenerates config or type definition files.                            | See subcommands below.                                                                                                                        |\n| `regen types`       | Regenerates `prasmoid.d.ts`.                                            | `prasmoid regen types`                                                                                                                        |\n| `regen config`      | Regenerates `prasmoid.config.js`.                                       | `prasmoid regen config`                                                                                                                       |\n| `upgrade`           | Updates Prasmoid itself to the latest version.                          | `prasmoid upgrade`                                                                                                                            |\n| `version`           | Shows the current version of Prasmoid.                                  | `prasmoid version`                                                                                                                            |\n\n## Extending Prasmoid with Custom Commands\n\nPrasmoid's most powerful and unique feature is its extensibility through custom JavaScript commands. This allows you to automate any project-specific workflow directly within your CLI, without needing Node.js installed on your system.\n\n### How it Works: The Embedded JavaScript Runtime\n\nPrasmoid includes a lightweight, high-performance JavaScript runtime embedded directly within its Go binary. This runtime provides a Node.js-like environment, offering synchronous APIs for common modules such as `fs`, `os`, `path`, `child_process`, and a custom `prasmoid` module for CLI-specific interactions.\n\nThis means you can write powerful automation scripts in JavaScript, and Prasmoid will execute them natively, making your custom commands fast, portable, and truly zero-dependency for end-users.\n\n### Creating a Custom Command\n\n1.  **Generate the command file:**\n\n    ```bash\n    prasmoid commands add deploy\n    ```\n\n    This will create a file like `.prasmoid/commands/deploy.js`.\n\n2.  **Edit the file** to define your command's logic. Prasmoid automatically adds type definitions (`prasmoid.d.ts`) for autocompletion and type-checking in editors like VS Code.\n\n    ```javascript\n    // .prasmoid/commands/hello.js\n\n    /// \u003creference path=\"../../prasmoid.d.ts\" /\u003e\n    const prasmoid = require(\"prasmoid\");\n    const fs = require(\"fs\"); // Example: You can use fs module\n\n    prasmoid.Command({\n      // The main function to run when the command is executed\n      run: (ctx) =\u003e {\n        const name = ctx.Flags().get(\"name\") || \"World\";\n        console.green(`Hello, ${name}!`); // Use Prasmoid's colored console\n\n        const args = ctx.Args();\n        if (args.length \u003e 0) {\n          console.yellow(\"Arguments received:\", args.join(\", \"));\n        }\n\n        // Example: Read a file using the embedded fs module\n        try {\n          const content = fs.readFileSync(\"somefile.txt\", \"utf8\");\n          console.log(\"File content:\", content);\n        } catch (e) {\n          console.red(\"Error reading file:\", e.message);\n        }\n      },\n\n      // A short description shown in the help list\n      short: \"Prints a greeting.\",\n\n      // A longer, more detailed description for 'prasmoid help hello'\n      long: \"A simple command that prints a greeting. You can use the --name flag to customize the greeting.\\n\\nExample:\\n  prasmoid hello --name 'Alice'\",\n\n      // Define command-line flags\n      flags: [\n        {\n          name: \"name\",\n          shorthand: \"n\",\n          type: \"string\",\n          default: \"World\",\n          description: \"The name to greet.\",\n        },\n      ],\n    });\n    ```\n\n3.  **Run your custom command:**\n\n    ```bash\n    $ prasmoid hello\n    # Output: Hello, World!\n\n    $ prasmoid hello --name \"Prasmoid\" an-argument\n    # Output: Hello, Prasmoid!\n    #         Arguments received: an-argument\n    ```\n\n### Available JavaScript Modules \u0026 APIs\n\nThe embedded runtime provides a subset of Node.js-like APIs, focusing on synchronous operations suitable for CLI scripting:\n\n- **`prasmoid`**: Custom module for CLI interactions.\n  - `prasmoid.Command(config)`: Registers a new command.\n  - `prasmoid.getMetadata(key)`: Reads values from `metadata.json`.\n  - `ctx.Args()`: Get command-line arguments.\n  - `ctx.Flags().get(name)`: Get flag values.\n- **`console`**: Enhanced logging with color support (`console.log`, `console.red`, `console.green`, `console.color`, etc.).\n- **`fs`**: Synchronous file system operations (`fs.readFileSync`, `fs.writeFileSync`, `fs.existsSync`, `fs.readdirSync`, etc.).\n- **`os`**: Operating system information (`os.arch`, `os.platform`, `os.homedir`, `os.tmpdir`, etc.).\n- **`child_process`**: Execute shell commands synchronously (`child_process.execSync`).\n- **`process`**: Process information and control (`process.exit`, `process.cwd`, `process.env`, `process.uptime`, `process.memoryUsage`, `process.nextTick`).\n- **`path`**: Utilities for working with file paths (`path.join`, `path.resolve`, `path.basename`, `path.extname`, etc.).\n\n\u003e [!NOTE]\n\u003e The embedded runtime currently supports **synchronous** file system operations only. Asynchronous functions (e.g., `fs.readFile`) are not implemented.\n\n---\n\n## Contributing\n\nWe welcome contributions from the community! Whether it's bug reports, feature requests, or code contributions, your help is invaluable.\n\n- **Report Bugs**: If you find an issue, please open a [GitHub Issue](https://github.com/PRASSamin/prasmoid/issues).\n- **Suggest Features**: Have an idea for a new feature? Open an issue to discuss it.\n\n---\n\n## 💖 Credits\n\n- **clorteau** – for the Arch, .deb and .rpm packages - [GitHub](https://github.com/clorteau)\n\n---\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprassamin%2Fprasmoid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprassamin%2Fprasmoid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprassamin%2Fprasmoid/lists"}