Tasks and the local service

This guide shows how to save personal command shortcuts and expose resources generated by application presets to other local applications over HTTP.

Save common commands

Save a complete command as a task:

shine task save logs -- tail -f /var/log/example.log
shine task save kill-port -- sh -c 'lsof -ti :3000 | xargs kill'
shine task save project-check --cwd ~/src/example -- bun run check

Run it later from any directory:

shine task run logs
shine run logs
shine task list
shine task info kill-port

Tasks are stored in tasks.toml under the active Shine runtime directory. SHINE_CONFIG_DIR or the global --config-dir selects the corresponding task list. A task saved with --cwd always starts there; without it, the task uses the caller's current directory.

Shine stores and executes an argument array directly without adding a shell. Argument boundaries and the child exit code are preserved. For pipes, redirection, variable expansion, or globs, include the shell in the task, such as sh -c '...'. Windows does not include sh; that form is Unix-only.

Replace or delete a task:

shine task save logs --force -- journalctl -f
shine task delete logs

Task names may contain letters, numbers, dots, hyphens, and underscores and must start with a letter or number.

Generate application helper resources

Some application presets declare an artifact script that generates extra files from current configuration:

shine app artifact apply surge

app artifact apply is explicit. shine app install, shine update, and shine upgrade do not implicitly run artifact scripts. It displays a security Plan; non-interactive callers must add --yes. A script failure fails the command and its output is shown directly.

Artifact scripts receive configured [artifact].env sources only, plus Shine-provided path variables:

Variable	Purpose
SHINE_APP_ID	Current application preset ID
SHINE_APP_DIR	Application directory used to run the script; points to the overlay when it provides the script
SHINE_APP_SOURCE_DIR	Base application preset directory
SHINE_APP_OVERLAY_DIR	Current application overlay directory; unset without an overlay
SHINE_APP_HTTP_DIR	Publishable application directory under ~/.shine/http/app/<APP_ID>/
SHINE_CONFIG_DIR	Current Shine runtime directory
SHINE_CACHE_DIR	Current application cache directory
SHINE_STATE_DIR	Current application state directory

Each environment source must also appear in [permissions].environment; missing optional sources are omitted. Values are passed as stored. Secret-classified inputs are Plan-bound by an opaque version but are not decrypted automatically and do not trigger GPG, age, or Touch ID prompts.

Start the local HTTP service

Start the service when another local application needs files under ~/.shine/http/:

shine serve start

It listens on 127.0.0.1:6174 by default. Install the native per-user background service or task:

shine serve install
shine serve status
shine serve uninstall

Shine uses launchd on macOS, a systemd user unit on Linux, and a limited current-user scheduled task on Windows. Windows starts it at login; Linux and macOS enable their user service. All modes bind only to 127.0.0.1 and preserve the active --config-dir.

Print a URL for a generated resource:

shine serve url app/surge/custom-rules.sgmodule
shine serve url app/surge/custom-rules.sgmodule --port 6180

Never put tokens, private keys, cookies, or other sensitive content under ~/.shine/http/. The service has no additional authentication; on a shared machine, other local users may be able to read files exposed through the port.