Skip to content

Write and run a script

Goal: write a short Python script that calls the platform with the active context's connection, and run it from the TUI.

Prerequisites

  • An active context (Switch context). The script gets that context as environment variables; you never put a host or key in it.

Steps

  1. Open Scripts: Config top tab, 3 (Scripts) in the default layout. The list shows the built-in scripts first (read-only: list_workers.py, create_worker.py, start_worker.py, stop_worker.py, delete_worker.py, binance.py), then yours from ~/.config/virtufin/tui/examples/.
  2. Create one: press a. A file new_script_NN.py is created in ~/.config/virtufin/tui/examples/ from the template and opened in the editor. (To give it another name, rename the file on disk.)
  3. Edit it. The template shows the contract. A minimal script:

    import asyncio
    
    from _rpc import api_client, invoke
    
    
    async def run():
        async with api_client() as api:
            result = await invoke(api, "workmanager", "ListWorkers")
            print(f"Workers: {len(result.get('workers', []))}")
    
    
    if __name__ == "__main__":
        asyncio.run(run())
    

    api_client() connects with the VIRTUFIN_TUI_API_* variables; invoke() calls any api RPC by service and method name through gRPC reflection. To run catalog operations instead (workers.list, triggers.schedule, ...), see The TUI's API › Scripts. 4. Save: s (user scripts only). 5. Run: r. The script runs as a subprocess of the TUI's own Python, with the built-in examples/ on PYTHONPATH.

With a form: put <name>.form.json next to <name>.py. The pane then shows the form; fill it in and press its submit button (its label comes from the form's submit.label, e.g. Create Worker; e toggles form and code). The values reach the script as JSON in VIRTUFIN_TUI_FORM_DATA. See create_worker.py / create_worker.form.json and Scripts › Script + form pairs.

Unattended at connect: list the file name in init_scripts in ~/.config/virtufin/tui/config.toml and put the file in ~/.config/virtufin/tui/scripts/; it runs after each connect, output to tui.log (Scripts › init_scripts).

What you should see

  • The script's output streaming into the output panel below the editor.
  • Ctrl+C with the output focused copies the whole output; in the editor it copies the selection. (Ctrl+C never quits; q does.)

Troubleshooting

Symptom Cause and fix
Built-in scripts cannot be overwritten. ... on s Built-ins are read-only: press a for a user script and copy the code over.
Fill in the form and press its Submit button (e: code editor) on r The script has a .form.json; run it from the form.
No script selected Highlight a script in the list first.
Authentication errors in the output The active context's key is refused; see Switch context.
ModuleNotFoundError: _rpc when run outside the TUI _rpc.py is on PYTHONPATH only when the TUI runs the script.

Writes a script makes are not confirmed on a protected context and are not recorded on Infra › Changes: scripts run as their own processes with their own client. Reference: Scripts, Keybindings › Scripts.