python-scripttease/help/en/docs/usage/posix.md

# POSIX

Summary: Work with common POSIX-compliant commands.

## Available Commands

### append

Append content to a file. Argument is the file name.

- `content` (str): The content to be appended.

```ini
[add to the log file]
append: /path/to/file.log
content: This is a test.
```

### archive

Create an archive (tarball). Argument is the target file or directory.

- `absolute` (bool): Don't strip leading slashes from file names. Default `False`
- `exclude` (str): Exclude file name patterns.
- `file_name` (str): The name of the archive file. Default `archive.tgz`
- `strip` (int): Strip component paths to the given depth.
- `to_path` (str): The path to where the archive will be created. Default `.`
- `view` (bool): View the progress. Default `False`

```ini
[create an archive of the site]
archive: /path/to/file_or_directory
file_name: testing.tgz
to: /tmp
```

### certbot

Alias: ssl

Use Let's Encrypt (certbot) to acquire an SSL certificate. Argument is the domain name.

- `email`: The email address for "agree tos". Default: `webmaster@domain_name`
- `webroot`: The webroot to use. Default: `/var/www/maint/www`

```ini
[get an SSL cert]
ssl: example.app
email: webmaster@example.app
```

### copy

Copy a file or directory. First argument is the target file/directory. Second argument is the destination.

- `overwrite` (bool): Overwrite an existing target.
- `recursive` (bool): Copy directories recursively.

```ini
[copy a directory]
copy: /path/to/directory /path/to/new_directory
overwrite: yes
recursive: yes
```

### dir

Create a directory. Argument is the path.

- `group` (str): Set the group to the given group name.
- `mode` (str): Set the mode on the path.
- `owner` (str): Set the owner to the given owner name.
- `recursive` (str): Create the full path even if intermediate directories do not exist.

```ini
[create a directory]
dir: /path/to/directory
group: www-data
mode: 755
owner: deploy
recursive: yes
```

### extract

Extract an archive (tarball). Argument is the path to the archive file.

- `absolute` (bool): Don't strip leading slashes from file names. Default `False`
- `exclude` (str): Exclude file name patterns.
- `strip` (int): Strip component paths to the given depth.
- `to_path` (str): The path to where the archive will be created. Default `./`
- `view` (bool): View the progress. Default `False`

```ini
[extract an archive]
extract: /path/to/archive.tgz
```

### link

Create a symlink. First argument is the source.

- `force` (bool): Force creation of the link.
- `target` (str): The location of the link. Defaults to the current directory and the base name of the source.

```ini
[create a symlink]
link: /path/to/project/releases/1.0
cd: /path/to/project
force: yes
target: current
```

### move

Move a file or directory. First argument is the target. Second argument is the desitnation.

```ini
[move a file]
move: /path/to/file.txt /new/path/to/file.txt
```

### perms

Set permissions on a file or directory. Argument is the path.

- `group` (str): Set the group to the given group name.
- `mode` (str): Set the mode on the path.
- `owner` (str): Set the owner to the given owner name.
- `recursive` (bool): Apply permission recursively (directories only).

```ini
[set permissions on the shared directory]
perms: /path/to/project/shared
group: www-data
mode: 775
owner: deploy
recursive: yes
```

### push

Alias: rsync

Push (rsync) a path to a remote server. First argument is the local path. Second argument is the remote path.

- `delete` (bool): Delete existing files/directories. Default `False`
- `host` (str): The host name. Required.
- `key_file` (str): Use the given SSL (private) key.
- `links` (bool): Copy symlinks. Default `True
- `exclude` (str): Exclude patterns from the given (local) file.
- `port` (int): The TCP port on the host. Default: `22`
- `recursive` (bool): Operate recursively on directories.
- `user` (str): The username.

```ini
[push the project to the server]
push: /path/to/project /path/on/server
key_file: ~/.ssh/example_app
host: example.app
user: deploy
```

### remove

Remove a file or directory. Argument is the path.

- `force` (bool): Force the removal. Default `False`
- `recursive` (bool): Remove all directories in the path. Default `False`

```ini
[remove a directory]
remove: /path/to/directory
force: yes
recursive: yes
```

### replace

Replace something in a file. First argument is the path.

- `backup`: Backup file extension. Default `.b`
- `delimiiter`: The sed delimiter. Default: `/`
- `find`: The text to be found. Required.
- `sub`: The text to be replaced. Required.

```ini
[replace text in a file]
replace: /path/to/file.txt
find: testing
sub: 123 
```

### scopy

Copy a file to a remote server. First argument is the local file name. Second argument is the remote destination.

- `key_file` (str): The private key file to use for the connection.
- `host` (str): The host name. Required.
- `port` (int): The TCP port. Default: `22`
- `user` (str): The username. Required.

```ini
[copy a file to the server]
scopy: /path/to/local.txt path/to/remove.txt
host: example.app
user: deploy
```

### sync

Sync (rsync) local files and directories. First argument is the target. Second argument is the destination.

- `delete` (bool): Delete existing files/directories.
- `links` (bool): Copy symlinks.
- `exclude` (str): Exclude patterns from the given (local) file.
- `recursive` (bool): Operate recursively on directories.

```ini
[syncrhonize files on the local machine]
sync: /path/to/project /path/to/sync/directory
```

### touch

Touch a file, whether it exists or not. Argument is the path.

```ini
[touch a file]
touch: /path/to/file.txt
```

### wait

Wait for n number of seconds before continuing. Argument is the number of seconds.

```ini
[wait just a minute]
wait: 60
```

### write

Write to a file. Argument is the path.

- `content` (str): The content to write to the file. Replaces existing content.

```ini
[replace an existing file]
write: /path/to/file.txt
content: This whole file has been replaced.
```