KingsScript

Personal scripts behind a single command, kings: a generic core, plus one layer per company or project.

• Improve reuse: logs, prints, secrets and cache live in the core, and every layer uses them.
• Improve portability: company-specific scripts stay in their own repo, plugged in when needed.

Index

• Requirements
• Install
• Structure
• Commands
• Layers
  • Git hooks
  • Checkup
• Core library
• For AI agents
• Contributing
• Author

Requirements

Tool	Version
	Any recent
	3.2, the system /bin/bash
	Any

Some commands need more — each one says so when it's missing:

Tool	Used by
gh (logged in)	git-prreview
swiftformat	git-swiftformatstaged
Xcode	xcode-*
jq	slack-test
Python 3	graph, docs-check
Graphify	graph
Node 20+ and npm install --prefix Scripts/Design/Figma	fig-*

Install

# Clone anywhere — the repo stays there, the installer only records its path
git clone https://github.com/Kings-Platform/KingsScript.git

# Install: ~/.kingsScripts, the kings command, git hooks and a block in ~/.zshrc
./KingsScript/install/install.sh

# Load it in the current terminal and check
source ~/.zshrc
kings help

# Register the layers this machine uses
kings layer add /path/to/some-layer

Note

Run the install again after moving the repo. To remove it: ./KingsScript/install/uninstall.sh (add --purge to also delete ~/.kingsScripts).

Structure

Repo:

Folder	What it is
Scripts/main.sh	Dispatcher — core commands first, then each layer
Scripts/Core/	Shared library (see Core library)
Scripts/Kings/	Commands that manage kings itself
Scripts/<Area>/<Subject>/	Every other command, one folder per subject — with a README.md when it needs one
install/	Install and uninstall
templates/layer/	Starting point for a new layer

Machine (~/.kingsScripts/, never committed):

Path	What it is
bin/kings	The command
config.env	Machine settings, loaded by every command — see config.example.env
layers	Registered layers, one path per line
cache.txt	key=value state shared by every command
logs/	One YYYY-MM-DD.log per day — past months zipped as YYYY-MM.zip
git-hooks/	Global git hooks, all forwarding to the layers
backup/	.zshrc copies taken by the installer

Commands

Kings:

Command	What it does
kings help	Lists every command: core first, then each layer
kings layer list | add | remove | create	Manages the layers of this machine
kings hooks on | off | status	Turns every layer's git hooks on or off
kings checkup [--force]	Runs the periodic tasks now
kings secret set | delete | status <NAME>	Keeps secrets in the Keychain — set asks for the value

Tools:

Area	Command	What it does
Git	git-swiftformatstaged	Formats the staged .swift files and stages them again — partially staged files are skipped
	git-prreview <PR>	PR review comments as a markdown table
	git-deletebranch [branch]	Deletes a local branch, the current one by default
Xcode	xcode-simulator [device]	Opens the Simulator, booting the device if given
	xcode-deeplink <url>	Opens a URL in the booted simulator
Slack	slack-test [channel]	Reads and posts in a channel to check a Slack app
Installers	install-tabby	Installs Tabby without admin rights
	install-gem <gem> [version]	Installs a Ruby gem without admin rights
AI	graph	Queries the repo's Graphify dependency graph
	docs-check	Finds broken links, anchors and orphan pages in docs
	ai-update [--auto]	Updates the installed Claude Code plugins — pulls marketplaces that are local clones first
Design	fig-parse <file.fig>	Extracts layout, colors and text from a Figma file
	fig-check [file.fig]	Regression check of fig-parse

Exit codes: 0 success · 1 error · 127 unknown command.

Layers

A layer is a separate repo (or folder) with its own commands, git hooks and periodic tasks. kings layer create <path> scaffolds one.

File	Role
layer.env	LAYER_NAME, shown in kings help and in the logs
main.sh	The layer's commands
hooks/<hook>.sh	Git hooks (optional)
checkup.sh	Periodic tasks (optional)
Scripts/	The scripts themselves

main.sh is a case over the command name:

case "$cmd" in
  help)   printf '  %-34s %s\n' "deploy <env>" "Deploys the app" ;;   # one line per command
  deploy) exec "$LAYER_DIR/Scripts/Deploy/deploy.sh" "$@" ;;
  *)      exit 127 ;;                                                  # not mine: next layer
esac

Every command:

• takes input as arguments and never prompts — if it must, its help line says so
• prints the result to stdout and messages through print_*
• exits 0 or 1 — 127 only means "not mine"

Git hooks

Every hook of every repo goes through kings hooks run <hook>, which:

1. Runs the repo's own .git/hooks/<hook> — git skips it when core.hooksPath is global
2. Runs each layer's hooks/<hook>.sh, unless kings hooks off

Hooks run in all repos, so a project-specific one checks git config --get remote.origin.url first and exits 0 elsewhere.

Checkup

Each new terminal runs kings checkup in the background. checkup.sh registers the tasks:

checkup_task cleanup weekly "$LAYER_DIR/Scripts/Cleanup/cleanup.sh"   # daily | weekly | monthly

A task runs at most once per period, counting only successful runs. The core has two:

Task	Period	What it does
log-archive	Monthly	Zips last month's logs
ai-update	Daily	kings ai-update --auto — skips a marketplace clone that isn't clean and on its default branch, and notifies when a plugin was updated

Core library

Loaded with . "$KINGS_CORE/<module>.sh".

Module	Functions
print.sh	print_info, print_title, print_success, print_warn, print_error — stderr and log
log.sh	log <message>, log_run <cmd> (output to the log only), log_file
secrets.sh	secret_get <NAME> — env var first, then Keychain; secret_set, secret_delete, secret_source
cache.sh	cache_get, cache_set, cache_unset
notify.sh	notify_banner, notify_alert, notify_dialog
zshrc.sh	zshrc_set_block <name> <content>, zshrc_remove_block, zshrc_has_block — named blocks in ~/.zshrc
timer.sh	timer_elapsed — HH:MM:SS since the script started
layers.sh	layers_list, layer_name, layer_is_valid

Layer scripts also get KINGS_CORE, KINGS_ROOT, KINGS_HOME, KINGS_CMD and everything in config.env. Log lines look like:

[2026-09-29 14:03:12] [acme:deploy #48213] Deploying to staging

For AI agents

• kings help lists what exists — prefer a command over a one-off script
• Not on the PATH? Call ~/.kingsScripts/bin/kings
• Result on stdout, messages on stderr, no colors outside a terminal
• Debug with today's log, filtering by the command label ([acme:deploy)
• Ask before install/*.sh, layer add | remove and secret set | delete

Snippet for the agent's global instructions (~/.claude/CLAUDE.md, AGENTS.md):

## KingsScript
Personal scripts run through `kings <command>` (or `~/.kingsScripts/bin/kings`). Run
`kings help` before writing a new script; new personal scripts become `kings` commands.
Logs: `~/.kingsScripts/logs/<date>.log`. Docs: https://github.com/Kings-Platform/KingsScript

Contributing

Script structure, rules and how to test: CONTRIBUTING.md.

---

Author

Gui Reis