Pinokio

When a menu item in pinokio.js defines a params object, those values are passed to the script specified by href. Inside the target script (e.g., a .json file), these parameters are accessible via the input variable.

For example, if pinokio.js passes { url: "https://example.com" }, a script using the template string {{input.url}} will resolve to https://example.com.

{
  "run": [{
    "method": "shell.run",
    "params": {
      "message": "git clone {{input.url}}"
    }
  }]
}

Pinokio allows you to reference local files using relative paths. The path is automatically resolved relative to the directory containing the currently running script.

For example, if start.js is located in /PINOKIO_HOME/api/myapp, calling a script with the URI subroutine.json will cause the interpreter to look for and execute /PINOKIO_HOME/api/myapp/subroutine.json.

// start.js
module.exports = {
  "run": [{
    "method": "script.start",
    "params": {
      "uri": "subroutine.json"
    }
  }]
}

The _ variable provides access to lodash methods directly within template expressions. This allows for complex data manipulation (like finding differences between arrays or sampling items) inside JSON scripts.

{
  "run": [{
    "method": "log",
    "params": {
      "raw": "{{_.sample(self.friends)}}"
    }
  }]
}

Variables prefixed with local. (e.g., local.items, local.prompt) are used to store state within a script execution.

Key characteristics:

• They are reset whenever the script finishes running.
• They persist across steps within a single execution run.
• You can set or update them using the local.set API.

Pinokio allows you to build user interfaces using JSON or JavaScript. A project's UI is composed of three primary components:

1. shortcut: Defines how the application is displayed on the Pinokio home page after it is downloaded. This is configured using pinokio.js.
2. app: Defines the actual layout and interface of the installed application page. This is configured using pinokio.js.
3. info: Defines how the application is presented on the Pinokio discover page and the official website (https://pinokio.computer). This is configured using pinokio_meta.json.

The self keyword allows you to access custom key/value pairs defined within the script object itself. A Pinokio script is a JSON object that can contain a run array and any other custom keys.

Example: Using self to handle platform-specific commands.

{
  "cmds": {
    "win32": "dir",
    "darwin": "ls",
    "linux": "ls"
  },
  "run": [{
    "method": "shell.run",
    "params": {
      "message": "{{self.cmds[platform]}}"
    }
  }]
}

Pinokio operates within an isolated folder called the pinokio home. This ensures that all installations (like Python, Node.js, or FFmpeg) do not interfere with your global system configuration. You can set or change this location in the settings tab.

Inside the pinokio home folder, the following directories are used:

• api: Stores all downloaded apps and scripts. Each subfolder here appears as an app in the Pinokio UI.
• bin: Stores globally installed modules shared across multiple apps (e.g., ffmpeg, nodejs, python) to prevent redundant installations.
• cache: Stores files automatically cached by apps. If an app fails, deleting this folder and restarting can often resolve issues.
• drive: Stores virtual drives created via the fs.link API.
• logs: Contains log files for each individual app.

Pinokio uses a template interpreter to allow dynamic command generation.

Template Syntax: Wrap expressions in {{ }}. These are evaluated at the beginning of every step in the run array.

Capabilities:

1. JavaScript Evaluation: Run any Node.js expression (e.g., {{Buffer.from(input.images[0], "base64")}}).
2. Memory Variables: Access system and state variables (e.g., {{current}} returns the index of the currently executing step).
3. Input Passing: The return value of a previous step is passed to the next step as the {{input}} variable.

Example:

{
  "method": "local.set",
  "params": {
    "name": "{{input}}"
  }
}