Where to start
- Open “Settings” → “Tools”, click “Choose script…” in the “Your own script” row and pick a script file. A script fence appears on the desktop and runs the script once right away. “New tool” → “Your own script…” in the tray menu does the same.
- You can also start from an example. Add one such as “Weather”, then right-click its fence and choose “Edit script”. The script opens in Notepad. Change it and save it, then choose “Run now”.
Which scripts work
PowerShell (.ps1), Python (.py, .pyw), batch files (.cmd, .bat), JavaScript (.js) and programs (.exe) all work. Python and JavaScript need Python and Node.js installed first.
A script runs in its own folder and opens no window. When a PowerShell script contains emoji or letters beyond plain English, save it as “UTF-8 with BOM”, or they show up garbled. In Notepad, choose “Save as” and pick it under “Encoding”.
How long and how often
A script runs for at most 10 seconds each time. After 10 seconds PecoFence stops it, and the fence says so.
Right-click the fence and choose how often it runs under “Run interval”: 1, 5, 15 or 30 minutes, or 1 or 3 hours. The default is 30 minutes. “Run now” runs it once right away.
A fence shows at most 40 lines, each at most 300 characters long. The bottom line of the fence shows the script's name and when it last ran.
A complete example
Save the lines below as a .ps1 file, then choose it under “Your own script”. Each line the script prints becomes a line in the fence.
# My links. Save as "UTF-8 with BOM".
"Today is $(Get-Date -Format 'dddd, MMMM d') | icon=📅"
"---"
"PecoFence manual | href=https://pecofence.jiang.jp/manual/ icon=📖"
"Open Downloads | open='$env:USERPROFILE\Downloads' icon=📁"
"Copy my email address | [email protected] icon=✉️"
"Drive C: $([int]((Get-PSDrive C).Free / 1GB)) GB free | color=green"
The text before the bar | is what the fence shows. After it come the parameters, written as name=value. Put a value with spaces in quotes. A line without a bar shows as plain text.
Make a row clickable or change its look
| Write | What it does |
href=web address | A click opens the web address in the browser |
open=path | A click opens the file or folder. A path without a drive letter starts at the script's folder |
run=program param1=argument | A click runs the program without a window. Write its arguments as param1=, param2=… |
copy=text | A click copies the text |
action=value | A click runs the script again with this value, see the next section |
refresh=true | The script runs again after the click. Works together with any of the above |
color=color | The text color: red, green, orange, yellow, blue, purple, gray, or #rrggbb |
icon=text | Shown at the start of the row, such as an emoji |
tooltip=text | The tip shown while the pointer rests on the row |
A line with only --- | Draws a separator line |
[ ] or [x] at the start | Drawn as a to-do box, [x] is ticked |
When a row has several clickable parameters, only the first counts, in this order: href, open, run, copy, action. The format comes from SwiftBar, a menu bar tool for macOS.
Run the script again with a click
When you click a row with action=, PecoFence runs the script again right away and hands it the value in PECOFENCE_ACTION. The script checks the value first, does what it asks, then prints as usual. On a scheduled run and on “Run now”, the value is empty.
# Water log: each click adds a glass
$file = Join-Path $env:PECOFENCE_DATA 'count.txt'
$n = if (Test-Path $file) { [int](Get-Content $file) } else { 0 }
if ($env:PECOFENCE_ACTION -eq 'add') { $n++; Set-Content $file $n }
"Glasses of water today: $n"
"One more glass | action=add icon=💧"
To-dos work the same way: click the box of a to-do with action=, and it is ticked at once. What the script prints next decides what stays.
Scripts that keep running
Write <pecofence.type>streamable</pecofence.type> in a comment at the top of the script, and it keeps running, without the 10-second limit. Every line it prints shows at once. After a line with ~~~, the next line starts a new screen that replaces what was shown. The fence keeps the newest 40 lines. The “PC status” example is written this way.
# <pecofence.type>streamable</pecofence.type>
# Shows the time every second
while ($true) {
"~~~"
"It is $(Get-Date -Format 'HH:mm:ss')"
Start-Sleep -Seconds 1
}
Such a script is always running. When you click a row with action=, the value goes to the script's standard input as one line of text: the place where a script normally reads what you type. The script ends when you delete its fence, turn off the “Tools” switch or quit PecoFence. When the script ends by itself, the fence keeps what it showed last, and PecoFence starts the script again after the run interval.
Environment variables a script can read
Environment variables are a few values PecoFence hands to a script when it runs it. In PowerShell you write $env:NAME, in Python os.environ["NAME"].
PECOFENCE | Always 1. A script can use it to tell whether PecoFence is running it |
PECOFENCE_ACTION | The action= value of the row you clicked. Empty on a scheduled run and on “Run now” |
PECOFENCE_DATA | A folder of this fence's own, for what the script needs to remember. PecoFence creates it for you |
PECOFENCE_THEME | PecoFence's current color mode: light or dark |
PECOFENCE_FENCE | The fence's ID |
PECOFENCE_DATA is in the scripts-data folder inside the configuration folder, named after the fence's ID. “Settings” → “Layout and backups” shows where the configuration folder is. The example scripts are in the scripts folder of the same configuration folder.
When something goes wrong
When a script fails, the fence shows the first line of the error, and its bottom line gives the exit code. The fence also says so when the script file is missing, when this kind of file can't run, or when the program that runs it (such as Python) isn't installed. Once you've fixed the script, right-click the fence and choose “Run now” to try again.