| Name | dosh-cli JSON |
| Version |
0.1.4
JSON |
| download |
| home_page | None |
| Summary | Command line interface of DOSH, a tool for managing your tasks. |
| upload_time | 2024-08-31 12:58:34 |
| maintainer | None |
| docs_url | None |
| author | Gökmen Görgen |
| requires_python | <3.13,>=3.9 |
| license | MIT |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# DOSH-CLI - shell-independent task manager (CLI)
[](https://dl.circleci.com/status-badge/redirect/gh/gkmngrgn/dosh-cli/tree/main)
**DOSH-CLI** is a command-line interface of [**DOSH-CORE**](https://github.com/gkmngrgn/dosh-core) to run your tasks on any platform, on any shell. Define your tasks, aliases, environments in a `dosh.lua` file and run `dosh`. DOSH will work like a CLI app reading your config file.
<img src="https://raw.githubusercontent.com/gkmngrgn/dosh-core/main/dosh-logo.svg"
width="200"
alt="DOSH logo" />
## INSTALLATION
We have many ways to install DOSH CLI. You can prefer to install it using the Python package manager, or you can use the installer script for Linux and MacOS, or if you are a Windows user, you can download the Windows installer.
Currently, our CircleCI builds app for these operating systems:
- Linux (aarch64, x86_64)
- MacOS (x86_64)
- Windows (amd64)
Also we build these targets manually:
- MacOS (arm64) using `package.sh`
- Windows Installer (amd64) using `package_for_windows.sh`
### BASH (for Linux, MacOS)
```shell
sh <(curl https://raw.githubusercontent.com/gkmngrgn/dosh-cli/main/install.sh)
```
### WINDOWS
Download the installer (`dosh-cli-windows-amd64-VERSION-installer.zip`) from [GitHub Release](https://github.com/gkmngrgn/dosh-cli/releases/latest).
### PYTHON
```shell
pip install --user dosh-cli
```
Or if you have `pipx`:
```shell
pipx install dosh-cli
```
## ANATOMY OF `dosh.lua`
```lua
local name = "there" -- you can use all features of Lua programming language.
local function hello(there) -- even you can define your custom functions.
there = there or name
local message = "Hello, " .. there .. "!"
cmd.run("osascript -e 'display notification \"" .. message .. "\" with title \"Hi!\"'")
end
cmd.add_task{ -- cmd comes from dosh.
name="hello", -- task name, or subcommand for your cli.
description="say hello", -- task description for the help output.
required_commands={"osascript"}, -- check if the programs exist before running the task.
required_platforms={"macos"}, -- check if the current operating system is available to run the task.
environments={"development", "staging"}, -- DOSH_ENV variable should be either development or staging to run this task.
command=hello -- run hello function with its parameters when the task ran.
}
```
When you run this command on MacOS, you will get a notification popup on the screen and see some logs in the console:
```shell
$ DOSH_ENV="development" dosh hello lua
DOSH => [RUN] osascript -e 'display notification "Hello, lua!" with title "Hi!"'
```
Take a look at the [`examples`](./examples) folder to find ready-in-use config files.
## ENVIRONMENT VARIABLES
#### HELP OUTPUT
Help outputs consist of four parts: **description**, **tasks**, **commands**, and **epilog**. The tasks will be generated getting task names and descriptions from your config file. The commands are including pre-defined dosh tasks and common task parameters. All help outputs start with a description and ends with an epilog if you have.
If you want to edit the default description and add an epilog to the help output, you can modify these variables:
- `env.HELP_DESCRIPTION`
- `env.HELP_EPILOG`
```
$ dosh help
dosh - shell-independent task manager # HELP_DESCRIPTION HERE
Tasks: # TASKS DEFINED BY THE USER
> hello say hello
Dosh commands:
> help print this output
> init initialize a new config in current working directory
> version print version of DOSH
-c, --config PATH specify config path (default: dosh.lua)
-d, --directory PATH change the working directory
-v|vv|vvv, --verbose increase the verbosity of messages:
1 - default, 2 - detailed, 3 - debug
Wikipedia says that an epilog is a piece of writing at the end of a work of # HELP_EPILOG HERE
literature, usually used to bring closure to the work.
```
#### OPERATING SYSTEM TYPE
All the following variables will return `true` or `false` depending on the operating system that you ran dosh:
- `env.IS_LINUX`
- `env.IS_MACOS`
- `env.IS_WINDOWS`
#### SHELL TYPE
It's like OS type checking. It's useful if you use shell-specific package like `ohmyzsh`.
- `env.IS_BASH`
- `env.IS_PWSH`
- `env.IS_ZSH`
#### DOSH-SPECIFIC ENVIRONMENTS
Consider you have some tasks that help you to test the project on your local and you want to restrict the task to prevent running it on the server by mistake. So the method `cmd.add_task` has an `environments` parameter and you can set your environment name for each target.
- `DOSH_ENV` (define it on your `~/.profile` file or CI/CD service)
_Check out the file [`dosh_environments.lua`](./examples/dosh_environments.lua) for example usage._
## COMMANDS
#### GENERAL PURPOSE
The main purpose of dosh to write one script that works on multiple operating systems and different shells. But it has to have a limit and it's nonsense to define functions for each cli command. So if you want to run a cli app (like `exa`, `bat`, `helix`, etc.), then you can use `cmd.run` for it.
_Check out the file [`dosh_greet.lua`](./examples/dosh_greet.lua) for example usage._
#### FILE SYSTEM OPERATIONS
There are some ready-made functions both to keep the code readable and to make it work the same in all operating systems. You know Windows prefers backslash as a path separator but with dosh, use always `/` as in `/foo/bar/baz`, let dosh to find the path in a common way.
_Check out the file [`dosh_config.lua`](./examples/dosh_config.lua) for example usage._
#### PACKAGE MANAGERS
There are many package managers and I'm not sure if we need to implement all of them. But at least dosh supports these three of them mostly:
- `cmd.brew_install` (for MacOS and Linux)
- `packages`: list of strings, required.
- `cask`: boolean, default is `false`.
- `taps`: list of strings, optional.
- `cmd.apt_install` (for Debian based Linux distros)
- `packages`: list of strings, required.
- `cmd.winget_install` (for Windows)
- `packages`: list of strings, required.
_Check out the file [`dosh_config.lua`](./examples/dosh_config.lua) for example usage._
#### FILE, FOLDER, COMMAND EXISTENCY
To check if file or folder exists, use `cmd.exists`. And if you want to check if a command exists, use `cmd.exists_command`.
#### LOGGING
You can manage the command outputs by defining the verbosity level. It's still possible to use `print`, but if you want to hide the command outputs completely or print them by the verbosity level, you have to use these logging functions:
- `cmd.debug`
- `cmd.info`
- `cmd.warning`
- `cmd.error`
For more information about the verbosity parameter of dosh, type `dosh help`.
_Check out the file [`dosh_greet.lua`](./examples/dosh_greet.lua) for example usage._
## QUESTIONS
### CAN I TRUST THIS PROJECT?
No. Don't trust any project. The source code is open, trust yourself and read the code.
### BUT DO YOU USE THIS PROJECT YOURSELF?
Yes, of course. I use multiple operating systems with different shells, and I'm too tired to write my scripts in multiple languages. This is why I created this project.
### BUT YOU COULD USE MAKEFILE, CMAKE, OR ANOTHER SIMILAR TOOL.
They are typically used to build and package software for distribution and are more geared towards building and managing software projects, while Dosh is more focused on running tasks from the command line. They serve different purposes and are not directly comparable. I keep these rules in mind:
- If I need to add a paragraph to the `README.md` file to explain how to configure the development environment and need to run some commands on my local, write a DOSH task named `setup` instead, and then add just one sentence: "You can start development with a magic command: dosh setup." Or better yet, tell the contributors to type `dosh help` to see all available tasks.
- If I don't want to create a project or repository for my personal tasks, I create `dosh.lua` in my home folder and write my tasks directly. For example, I have a task named `git-sync` that pulls the latest changes from the remote server or warns me if there's a conflict in the repository.
- If I need a command alias but also need to run the command in Windows and Mac OS X, or in powershell and zsh, DOSH makes it simple.
### WHY DOESN'T THIS PROJECT HAVE `DOSH.LUA`?
Because there's `pyproject.toml` and I use `poetry`. The other reason is that I don't want to create a circular dependency.
### WHY DOESN'T DOSH HAVE ANY REMOVE COMMAND?
Because it's too dangerous! I don't use any remove command in my scripts indeed. If you really need a remove command, you can run it with `cmd.run`. But remember, contributors of this project don't guarantee anything.
## CONTRIBUTION
Install these development dependencies manually:
- [poetry](https://python-poetry.org/)
- [poethepoet](https://github.com/nat-n/poethepoet)
- [poetry-dynamic-versioning](https://github.com/mtkennerly/poetry-dynamic-versioning)
- [pre-commit](https://pre-commit.com/)
```shell
$ poetry poe --help
[...]
CONFIGURED TASKS
lint Check code quality
test Run tests
name Filter tests by $name
```
Raw data
{
"_id": null,
"home_page": null,
"name": "dosh-cli",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.9",
"maintainer_email": null,
"keywords": null,
"author": "G\u00f6kmen G\u00f6rgen",
"author_email": "gkmngrgn@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/de/ce/6c0c7ba618de22cf7efede1447e4e338f95fedb55f6c804657c381dbd26b/dosh_cli-0.1.4.tar.gz",
"platform": null,
"description": "# DOSH-CLI - shell-independent task manager (CLI)\n\n[](https://dl.circleci.com/status-badge/redirect/gh/gkmngrgn/dosh-cli/tree/main)\n\n**DOSH-CLI** is a command-line interface of [**DOSH-CORE**](https://github.com/gkmngrgn/dosh-core) to run your tasks on any platform, on any shell. Define your tasks, aliases, environments in a `dosh.lua` file and run `dosh`. DOSH will work like a CLI app reading your config file.\n\n<img src=\"https://raw.githubusercontent.com/gkmngrgn/dosh-core/main/dosh-logo.svg\"\nwidth=\"200\"\nalt=\"DOSH logo\" />\n\n## INSTALLATION\n\nWe have many ways to install DOSH CLI. You can prefer to install it using the Python package manager, or you can use the installer script for Linux and MacOS, or if you are a Windows user, you can download the Windows installer.\n\nCurrently, our CircleCI builds app for these operating systems:\n\n- Linux (aarch64, x86_64)\n- MacOS (x86_64)\n- Windows (amd64)\n\nAlso we build these targets manually:\n\n- MacOS (arm64) using `package.sh`\n- Windows Installer (amd64) using `package_for_windows.sh`\n\n### BASH (for Linux, MacOS)\n\n```shell\nsh <(curl https://raw.githubusercontent.com/gkmngrgn/dosh-cli/main/install.sh)\n```\n\n### WINDOWS\n\nDownload the installer (`dosh-cli-windows-amd64-VERSION-installer.zip`) from [GitHub Release](https://github.com/gkmngrgn/dosh-cli/releases/latest).\n\n### PYTHON\n\n```shell\npip install --user dosh-cli\n```\n\nOr if you have `pipx`:\n\n```shell\npipx install dosh-cli\n```\n\n## ANATOMY OF `dosh.lua`\n\n```lua\nlocal name = \"there\" -- you can use all features of Lua programming language.\n\nlocal function hello(there) -- even you can define your custom functions.\nthere = there or name\nlocal message = \"Hello, \" .. there .. \"!\"\ncmd.run(\"osascript -e 'display notification \\\"\" .. message .. \"\\\" with title \\\"Hi!\\\"'\")\nend\n\ncmd.add_task{ -- cmd comes from dosh.\n name=\"hello\", -- task name, or subcommand for your cli.\n description=\"say hello\", -- task description for the help output.\n required_commands={\"osascript\"}, -- check if the programs exist before running the task.\n required_platforms={\"macos\"}, -- check if the current operating system is available to run the task.\n environments={\"development\", \"staging\"}, -- DOSH_ENV variable should be either development or staging to run this task.\n command=hello -- run hello function with its parameters when the task ran.\n}\n```\n\nWhen you run this command on MacOS, you will get a notification popup on the screen and see some logs in the console:\n\n```shell\n$ DOSH_ENV=\"development\" dosh hello lua\nDOSH => [RUN] osascript -e 'display notification \"Hello, lua!\" with title \"Hi!\"'\n```\n\nTake a look at the [`examples`](./examples) folder to find ready-in-use config files.\n\n## ENVIRONMENT VARIABLES\n\n#### HELP OUTPUT\n\nHelp outputs consist of four parts: **description**, **tasks**, **commands**, and **epilog**. The tasks will be generated getting task names and descriptions from your config file. The commands are including pre-defined dosh tasks and common task parameters. All help outputs start with a description and ends with an epilog if you have.\n\nIf you want to edit the default description and add an epilog to the help output, you can modify these variables:\n\n- `env.HELP_DESCRIPTION`\n- `env.HELP_EPILOG`\n\n```\n$ dosh help\ndosh - shell-independent task manager # HELP_DESCRIPTION HERE\n\nTasks: # TASKS DEFINED BY THE USER\n> hello say hello\n\nDosh commands:\n> help print this output\n> init initialize a new config in current working directory\n> version print version of DOSH\n\n-c, --config PATH specify config path (default: dosh.lua)\n-d, --directory PATH change the working directory\n-v|vv|vvv, --verbose increase the verbosity of messages:\n 1 - default, 2 - detailed, 3 - debug\n\nWikipedia says that an epilog is a piece of writing at the end of a work of # HELP_EPILOG HERE\nliterature, usually used to bring closure to the work.\n```\n\n#### OPERATING SYSTEM TYPE\n\nAll the following variables will return `true` or `false` depending on the operating system that you ran dosh:\n\n- `env.IS_LINUX`\n- `env.IS_MACOS`\n- `env.IS_WINDOWS`\n\n#### SHELL TYPE\n\nIt's like OS type checking. It's useful if you use shell-specific package like `ohmyzsh`.\n\n- `env.IS_BASH`\n- `env.IS_PWSH`\n- `env.IS_ZSH`\n\n#### DOSH-SPECIFIC ENVIRONMENTS\n\nConsider you have some tasks that help you to test the project on your local and you want to restrict the task to prevent running it on the server by mistake. So the method `cmd.add_task` has an `environments` parameter and you can set your environment name for each target.\n\n- `DOSH_ENV` (define it on your `~/.profile` file or CI/CD service)\n\n_Check out the file [`dosh_environments.lua`](./examples/dosh_environments.lua) for example usage._\n\n## COMMANDS\n\n#### GENERAL PURPOSE\n\nThe main purpose of dosh to write one script that works on multiple operating systems and different shells. But it has to have a limit and it's nonsense to define functions for each cli command. So if you want to run a cli app (like `exa`, `bat`, `helix`, etc.), then you can use `cmd.run` for it.\n\n_Check out the file [`dosh_greet.lua`](./examples/dosh_greet.lua) for example usage._\n\n#### FILE SYSTEM OPERATIONS\n\nThere are some ready-made functions both to keep the code readable and to make it work the same in all operating systems. You know Windows prefers backslash as a path separator but with dosh, use always `/` as in `/foo/bar/baz`, let dosh to find the path in a common way.\n\n_Check out the file [`dosh_config.lua`](./examples/dosh_config.lua) for example usage._\n\n#### PACKAGE MANAGERS\n\nThere are many package managers and I'm not sure if we need to implement all of them. But at least dosh supports these three of them mostly:\n\n- `cmd.brew_install` (for MacOS and Linux)\n\n- `packages`: list of strings, required.\n\n- `cask`: boolean, default is `false`.\n\n- `taps`: list of strings, optional.\n\n- `cmd.apt_install` (for Debian based Linux distros)\n\n- `packages`: list of strings, required.\n\n- `cmd.winget_install` (for Windows)\n\n- `packages`: list of strings, required.\n\n_Check out the file [`dosh_config.lua`](./examples/dosh_config.lua) for example usage._\n\n#### FILE, FOLDER, COMMAND EXISTENCY\n\nTo check if file or folder exists, use `cmd.exists`. And if you want to check if a command exists, use `cmd.exists_command`.\n\n#### LOGGING\n\nYou can manage the command outputs by defining the verbosity level. It's still possible to use `print`, but if you want to hide the command outputs completely or print them by the verbosity level, you have to use these logging functions:\n\n- `cmd.debug`\n- `cmd.info`\n- `cmd.warning`\n- `cmd.error`\n\nFor more information about the verbosity parameter of dosh, type `dosh help`.\n\n_Check out the file [`dosh_greet.lua`](./examples/dosh_greet.lua) for example usage._\n\n## QUESTIONS\n\n### CAN I TRUST THIS PROJECT?\n\nNo. Don't trust any project. The source code is open, trust yourself and read the code.\n\n### BUT DO YOU USE THIS PROJECT YOURSELF?\n\nYes, of course. I use multiple operating systems with different shells, and I'm too tired to write my scripts in multiple languages. This is why I created this project.\n\n### BUT YOU COULD USE MAKEFILE, CMAKE, OR ANOTHER SIMILAR TOOL.\n\nThey are typically used to build and package software for distribution and are more geared towards building and managing software projects, while Dosh is more focused on running tasks from the command line. They serve different purposes and are not directly comparable. I keep these rules in mind:\n\n- If I need to add a paragraph to the `README.md` file to explain how to configure the development environment and need to run some commands on my local, write a DOSH task named `setup` instead, and then add just one sentence: \"You can start development with a magic command: dosh setup.\" Or better yet, tell the contributors to type `dosh help` to see all available tasks.\n\n- If I don't want to create a project or repository for my personal tasks, I create `dosh.lua` in my home folder and write my tasks directly. For example, I have a task named `git-sync` that pulls the latest changes from the remote server or warns me if there's a conflict in the repository.\n\n- If I need a command alias but also need to run the command in Windows and Mac OS X, or in powershell and zsh, DOSH makes it simple.\n\n### WHY DOESN'T THIS PROJECT HAVE `DOSH.LUA`?\n\nBecause there's `pyproject.toml` and I use `poetry`. The other reason is that I don't want to create a circular dependency.\n\n### WHY DOESN'T DOSH HAVE ANY REMOVE COMMAND?\n\nBecause it's too dangerous! I don't use any remove command in my scripts indeed. If you really need a remove command, you can run it with `cmd.run`. But remember, contributors of this project don't guarantee anything.\n\n## CONTRIBUTION\n\nInstall these development dependencies manually:\n\n- [poetry](https://python-poetry.org/)\n- [poethepoet](https://github.com/nat-n/poethepoet)\n- [poetry-dynamic-versioning](https://github.com/mtkennerly/poetry-dynamic-versioning)\n- [pre-commit](https://pre-commit.com/)\n\n```shell\n$ poetry poe --help\n[...]\n\nCONFIGURED TASKS\n lint Check code quality\n test Run tests\n name Filter tests by $name\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Command line interface of DOSH, a tool for managing your tasks.",
"version": "0.1.4",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6919162cd0341682f8e36ce2d3981a48107cd5f8e30ffeb61f5b449b01c1fe8c",
"md5": "659f3749d9efa60a4d19dedc7a7e2fda",
"sha256": "c0ad28be57cf0a99b8a433b3d9eb0f15717ff653304a014a8b8061f18c8629eb"
},
"downloads": -1,
"filename": "dosh_cli-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "659f3749d9efa60a4d19dedc7a7e2fda",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.9",
"size": 8264,
"upload_time": "2024-08-31T12:58:32",
"upload_time_iso_8601": "2024-08-31T12:58:32.749178Z",
"url": "https://files.pythonhosted.org/packages/69/19/162cd0341682f8e36ce2d3981a48107cd5f8e30ffeb61f5b449b01c1fe8c/dosh_cli-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "dece6c0c7ba618de22cf7efede1447e4e338f95fedb55f6c804657c381dbd26b",
"md5": "66061b1230a3ce0b65b2488b4f38508c",
"sha256": "6821c48651192b0d9c4574612d29f8323a22e6842a9912f78672a0aa80d25f42"
},
"downloads": -1,
"filename": "dosh_cli-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "66061b1230a3ce0b65b2488b4f38508c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.9",
"size": 7443,
"upload_time": "2024-08-31T12:58:34",
"upload_time_iso_8601": "2024-08-31T12:58:34.302232Z",
"url": "https://files.pythonhosted.org/packages/de/ce/6c0c7ba618de22cf7efede1447e4e338f95fedb55f6c804657c381dbd26b/dosh_cli-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-31 12:58:34",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "dosh-cli"
}
