Tinkershell

A command line utility to remotely execute code on deployed Laravel instances through a SSH connection. Inspired by Tinkerwell and motivated by Electron's clunkiness.

⚠️ This is in early alpha testing and should not be used in production
   environments, end user discretion is advised.

Tinkershell has only been tested against Laravel 10.x version and will most likely have issues with older or newer versions. PRs are welcome.

Installation

curl -sSL https://raw.githubusercontent.com/yugarinn/tinkershell/main/install.sh | bash

Note that on Windows, git bash is required.

Configuration

Tinkershell expects a toml config file to exists in ~/.config/tinkershell/tinkershell.toml. The config file organizes connection environments under different sections, each section represents a single, unique connection. All connection sections must include four fields:

• ip_address: The ipv4 address of the remote server.
• ssh_username: The username to be used in the SSH connection.
• ssh_public_key: The path to the SSH public key to be used.
• project_path: The root path of the Laravel project in the remote server.

Only public/private keys SSH authentication is supported.

Example

[production]
ip_address = "34.12.123.12"
ssh_username = "yugarinn"
ssh_public_key = "~/.ssh/id_rsa"
project_path = "/home/yugarinn/laravel-app/"

[staging]
ip_address = "129.11.98.32"
ssh_username = "yugarinn"
ssh_public_key = "~/.ssh/id_rsa"
project_path = "/home/yugarinn/laravel-app/"

Usage

The executable expects two flags to be provided, -e one of the configured sections in the config file, and -f the path to the .php file to be executed.

tinkershell -e production -f processPendingPayments.php

All tinkershell executions are assigned a pseudo-unique ID that is used in two files, the default remote server log file and a local log file under ~/.config/tinkershell/logs/.

Silent run

A third, optional, flag -s can be provided to make tinkershell run silently. When this flag is provided, all output and logging are suppressed.

Example

$ cat ./helloFromTinkershell.php

dump('Hello from Tinkershell!');
dump(config('app.name'))

$ cat ~/.config/tinkershell/tinkershell.toml
[staging]
ip_address = "129.11.98.32"
ssh_username = "yugarinn"
ssh_public_key = "~/.ssh/id_rsa"
project_path = "/home/yugarinn/laravel-app/"

$ tinkershell -e staging -f ./helloFromTinkershell.php
=> [Tinkershell INFO] running process 'MTc2OTM2MjgxMzc4OA==' [PID: 3565347]...
Hello from Tinkershell!
My Laravel App
=> [Tinkershell INFO] running process 'MTc2OTM2MjgxMzc4OA==' [PID: 3565347]... done

Logs

A helper class Tinkershell is defined, which includes a log method that can be used to dump information to both the terminal and the log files.

$users = User::get();

foreach ($users as $user) {
    Tinkershell::log($user->name);
}

By default, Tinkershell stores logs under ~/.config/tinkershell/logs/.