Repository navigation
UserGuide en US.md
This guide describes 0.1.4 and reflects the current implementation. NikoTools saves recurring scripts, generates parameter forms before execution, and displays results in the IDE's native Run console. Scripts and tool paths are shared across projects in the same IDE configuration. Working directories, file browsing, and Android device selection use the current project window.
The current UI uses Chinese labels. This guide quotes those labels alongside their English meaning so you can find the relevant controls.
- Installation and prerequisites
- Your first run
- Managing scripts and templates
- Execution types
- Parameter template syntax
- Execution configuration
- Parameter metadata
- Android devices
- Output and stopping scripts
- Sharing, importing, and migration
- Practical examples
- Troubleshooting and FAQ
- Data locations and development
The minimum IntelliJ Platform build is 242 (IntelliJ IDEA 2024.2 series). The plugin requires a Java 21 runtime; a compatible IDE's bundled runtime is sufficient for use. You do not need to configure a development JDK just to run the plugin. The build baseline is IDEA 2024.2.6, targeting Android Studio, IntelliJ IDEA, PyCharm, and other IntelliJ Platform IDEs. Product version numbers differ, so check platform build numbers and actual compatibility.
- Obtain the built
NikoTools-0.1.4.zip. For local builds, see the project README. - Open Settings / Preferences → Plugins → gear icon → Install Plugin from Disk and select the ZIP.
- Restart if prompted. Open a project and use Tools → NikoTools or its sidebar icon.
- Once the plugin is published on Marketplace, it can also be installed through its listing. The publishing configuration in this project does not confirm that a listing is already available.
The plugin does not bundle Python, PowerShell, Bash, cmd, adb, or scrcpy. Install only the tools your scripts use. Ordinary scripts do not require Android devices or adb.
Open Settings → NikoTools, or use 环境路径 (Environment paths) in the tool window. You can specify absolute paths to these executable files:
| Setting | Purpose |
|---|---|
python |
Python interpreter; choose a virtual environment's Python executable when needed |
powershell |
PowerShell, usually pwsh or Windows powershell.exe
|
bash |
Bash; defaults to installed Git Bash on Windows |
cmd |
Windows batch interpreter cmd.exe
|
adb |
Android debugging tool |
scrcpy |
Android screen mirroring tool |
Empty fields display the detected default path as gray placeholder text and in a note below; missing tools are explicitly marked. These displayed defaults are not saved as overrides. Default resolution uses the PATH inherited by the IDE process. On Windows, Bash defaults to Git Bash: first the Git installation selected by PATH, then common system and per-user installation directories. Other platforms use Bash on PATH. Resolution priority is the script's interpreter override, then the global plugin setting, then default environment resolution. An invalid explicit path causes an error without fallback. Restart the IDE after changing system PATH when necessary. A virtual environment activated temporarily in the terminal is not automatically inherited by the plugin.
Prepare Python first, either on the IDE's PATH or in the environment settings.
-
Open NikoTools and click 新建脚本 (New script).
-
Set the name to
Greetingand select execution typepython. -
Enter this body:
import sys print("Hello, " + sys.argv[1])
-
Expand 执行配置 (Execution configuration) and enter this 参数数组 JSON (Arguments JSON):
["${name:World}"] -
Keep the remaining defaults and click 保存 (Save).
-
Double-click the saved script, enter a name in 运行参数 (Run parameters), and click 执行 (Run).
-
Find the greeting and exit code in the IDE's Run window.
The input is passed as a separate process argument without embedding it in Python source. Scripts without placeholders start without a parameter form.
The toolbar has seven actions. Hover over an icon to see its label.
| UI label | Action |
|---|---|
| 新建脚本 — New script | Create a script with a name, description, type, and body |
| 批量操作 — Batch operations | Import a directory or export the script library |
| 导入 — Import | Read script JSON from the clipboard |
| 排序 — Sort | Sort by usage frequency, addition order, or name |
| 环境路径 — Environment paths | Configure global interpreters and tools |
| 帮助 — Help | Open the script templates and parameter syntax dialog directly |
| 复制 SKILL — Copy SKILL | Copy the complete skill for converting user inputs to plugin parameter templates |
For scripts with parameters, 执行后保留弹窗 (Keep dialog open after running) is unchecked by default, so clicking 执行 (Run) closes the parameter dialog. Check it to retain inputs and run again. Scripts without parameters run directly without opening a dialog. Click 关闭 (Close) to dismiss it. The dialog allows other IDE operations; reopening the same script in the same project focuses its existing dialog, and an active run still prevents duplicate launches.
The table shows name, type, and description. Double-click a script to run it. Its context menu provides 执行脚本 (Run), 编辑脚本 (Edit), 分享脚本 (Share), and 删除脚本 (Delete). Use Shift+F10 or the context-menu key for the selected row. Press Delete on a selected script to request deletion (Backspace also works on macOS). Deletion asks for confirmation. Sorting is persisted across projects: usage frequency is highest first, addition order is oldest first, and names sort ascending ignoring case. Usage counts actual process launches, including reruns; cancellation and launch failures do not count. Ties retain addition order. Clicking empty table space does not operate on a script.
The toolbar 帮助 (Help) action or the editor’s 脚本模板与参数语法 (Script templates and parameter syntax) link opens a split view: select a template in the left list to switch the explanation and syntax on the right, with embedded parameter inputs and live substitution results below the source code. Results update immediately when text, choices, or paths change. Copy the source or preview result separately. A preview does not execute a command. Paste copied code into the body, choose the appropriate type and configuration, and save. There is no separate template library or “Save as template” action. The full built-in example, 全部参数类型演示 Bash (All parameter types: Bash), demonstrates ten types, defaults, and repeated references. Its paths 1 and 2 and token 1009 are demonstration values; its final output includes the actual token.
Use 复制 SKILL (Copy SKILL) to copy the complete script parameter conversion skill. Give it to an AI together with your requirements or existing script to convert pre-run user inputs into plugin controls and var declarations while preserving the script language and business logic. The button does not install the skill.
With the optional IDE Terminal plugin enabled, select text in a supported local terminal and use 新建 NikoTools 自定义脚本 (New NikoTools custom script) from its context menu. The selection opens in the script editor and is not executed before saving. New scripts default to powershell; choose the appropriate type for Bash, Python, or other content. The Terminal plugin is not required for the script list or execution.
| Type | Meaning of the body | Typical use |
|---|---|---|
powershell |
Commands or script source evaluated by PowerShell | PowerShell automation and Windows administration |
python |
Python source, or a recognized existing script file path | Data processing, file tools, and multiline logic |
bash |
Commands evaluated by bash -c
|
macOS/Linux commands, pipelines, and redirection |
batch |
Windows batch source or an existing batch file path |
.bat / .cmd scripts |
process |
One executable name or path; arguments go in the JSON array | Launching tools such as git, adb, or scrcpy directly |
The table displays process as 外部进程 (External process). For example, put git in the body and ["status", "--short"] in Arguments JSON. Do not put the entire git status --short command in the body. This type launches a program directly, without a shell, and does not interpret pipes, redirection, or shell variables. It is useful for a single executable; select a shell type for multiple commands or shell syntax.
For a one-line Python body, if the first parsed item identifies an existing file relative to the working directory, that file is run. Otherwise, the body becomes a temporary Python source file. Quote paths containing spaces and prefer Arguments JSON for arguments. Bash and PowerShell file invocations follow their language syntax, such as bash "./scripts/task.sh" or & './scripts/task.ps1'. For a batch file, put its arguments in Arguments JSON rather than after the path in the body.
Execution types do not convert scripts between platforms. batch requires Windows cmd; the other interpreters must be installed on the host.
The plugin discovers placeholders in the body, argument array, environment values, and working directory. Saving creates the corresponding form. Interpreter paths are not parsed as templates.
| Syntax | Meaning |
|---|---|
${name} |
Text input without an inline default |
${name:default} |
Text input with a default |
${name=default} |
Legacy default syntax |
${mode:On=1|Off=0} |
Choice showing labels but substituting 1 or 0; the first option is the default |
${name@text:example} |
Explicit text input; option-like content remains literal |
${description@multiline} |
Multiline input; preserves line breaks |
${retries@integer:3} |
Integer input; validated before execution |
${ratio@number:0.5} |
Integer or decimal input; validated before execution |
${cache@boolean:true} |
Checkbox; true/1 selects, false/0 or no default clears; outputs True/False
|
${mode@choice:On=1|Off=0} |
Explicit dropdown; defaults to the first option and outputs its value |
${environment@radio:Dev=dev|Prod=prod} |
Radio buttons; defaults to the first option and outputs its value |
${token@secret} |
Masked input; supports saved defaults and a visibility toggle; help previews show asterisks |
${input@file} |
File browser input |
${output@dir} |
Directory browser input; its metadata kind is directory
|
${input@file:./data.txt} |
File input with an inline default path |
Names accept letters, numbers, underscores, and Chinese characters, but not spaces. Repeated references share the same input. Conflicting repeated defaults, types, or choices cause errors. The \| in this Markdown table represents a literal | in actual scripts.
The unified format is ${name@type:default-or-options}. Omitting the type retains legacy parsing. @choice and @radio require options, including a single option; labels must be nonempty and unique, and values must be nonempty. Explicit input types such as @text treat A=1|B=2 literally. Bare references ${name} reuse the defined type; conflicting explicit types are rejected. Sharing removes input defaults while preserving types and options. Secret inputs support saved defaults and an eye icon to show or hide the value. Parameter labels omit required asterisks while required validation remains active; radio buttons are arranged horizontally.
Declarations separate an internal identifier from the displayed label:
var file = ${InputFile@file}
var mode = ${Mode:On=1|Off=0}
var output = ${OutputDirectory@dir}
Use ${file}, ${mode}, and ${output} elsewhere in the body or configuration. The identifier after the declaration keyword becomes the metadata id; the name inside braces becomes the form label. Use lowercase var for new declarations; legacy Var and pVal remain supported. Declarations must occupy their own lines. The plugin removes declaration lines before execution; they are not native shell or Python variable declarations.
File and directory browse buttons open the input directory or a file's parent directory (relative paths resolve from the current project root). Missing paths are searched upward for the nearest accessible directory: for A/B/C.txt, a missing C opens B, and a missing B opens A. Empty or malformed input, or a path with no usable ancestor, falls back to the project root in the current IDE window, and you can navigate outside the project. Without a project root, the IDE's default browsing behavior applies. Use @file for files and @dir for directories. Entering folders while browsing for a file is normal navigation. Manually entered paths are currently checked for required input only, not for existence or file/directory type.
Substitution is literal: quotes, backslashes, newlines, and shell metacharacters are not escaped automatically. Handle the target language's syntax when embedding input in source. Prefer Arguments JSON for paths or arbitrary text; each array item is a separate argument.
Some inputs offer 设为默认值 (Set as default) to persist their value. Boolean, choice, radio, and device controls do not have this button; secret controls support saved defaults. Saving changed templates synchronizes defaults, file/directory kinds, and choice options from the template. When templates are unchanged, saved custom defaults are preserved.
An argument such as "?verbose:--verbose" adds --verbose only when verbose is truthy. Booleans use case-insensitive true or 1, numbers use nonzero values, and other kinds use nonempty values. The controlling parameter must also be declared through a template. See the conditional argument example below.
For everyday scripts, name, type, and body are enough. Expand the configuration only when needed.
| Field | Default | When to change it |
|---|---|---|
| 工作目录 — Working directory | Current project root | Run in a subdirectory; relative paths resolve from the project root and the directory must exist |
| 解释器路径 — Interpreter path | Global setting, then IDE PATH | Choose a virtual environment or another interpreter; for process, override the actual executable |
| 依赖工具 — Required tools | Empty | Check additional tools before launch, such as adb, scrcpy; the selected interpreter is resolved automatically |
| 输出编码 — Output encoding | utf-8 |
Decode another output encoding, such as GBK
|
| 超时秒数 — Timeout seconds | Blank, unlimited | Positive integer; stop the process and traceable children after the limit |
| 参数数组 JSON — Arguments JSON | [] |
Separate arguments with templates or conditional items |
| 环境变量 JSON — Environment JSON | {} |
Override environment values for this child process, including templates |
Arguments example:
["--input", "${input@file}", "--output", "${output@dir}"]Environment example:
{"APP_MODE": "${mode:dev}", "LOG_LEVEL": "info"}Environment JSON is optional; ordinary scripts can keep {}. The child inherits the IDE environment, with tool paths, an Android serial when available, and an output directory added by the runner. Required tool directories are added to the run's PATH, and full executable paths are exposed as variables such as POPTOOLS_ADB and POPTOOLS_SCRCPY, following POPTOOLS_<UPPERCASE_TOOL>.
The runner sets PYTHONUTF8=1, PYTHONIOENCODING=utf-8, and PYTHONUNBUFFERED=1 after custom environment values. It also generates POPTOOLS_OUTPUT_DIR. The POPTOOLS prefix is retained for existing script compatibility.
Bash arguments are available as $1, $2, etc., with $0 fixed to poptool-script. Python uses sys.argv; batch uses %1, %2, etc. PowerShell arguments are appended to its -Command invocation, so write the body according to PowerShell's invocation semantics.
Metadata configures advanced form behavior. It is generated from templates and is not required for ordinary scripts. Use explicit template types for the ten ordinary controls. Edit the JSON array for optional fields, custom labels, or Android device inputs.
kind |
Control and behavior |
|---|---|
text |
Single-line text |
multiline |
Multiline text |
integer |
Integer, validated on submission |
number |
Decimal number, validated on submission |
boolean |
Checkbox, substituting True / False
|
choice |
Choice using its value; define options in the template |
radio |
Horizontal radio buttons using each option’s value
|
file |
File browser input |
directory |
Directory browser input |
secret |
Masked password input; substitution uses the actual text |
android_device |
Read-only serial of the IDE-selected device |
id matches the internal template name. label sets the display name, required controls nonblank validation, default supplies the initial value, and options provides dropdown or radio labels and values. The compatibility field placeholder can be stored in JSON, but the current form does not display it as a hint.
For a ${count:3} placeholder:
[
{
"id": "count",
"label": "Repeat count",
"kind": "integer",
"required": true,
"default": "3",
"options": []
}
]Save the script with its placeholders first, then edit the generated metadata to keep IDs consistent. Saving in the editor retains only parameters referenced by templates. Explicit kinds, defaults, and options follow template definitions. Existing scripts with ordinary text placeholders and metadata kinds such as integer, boolean, or secret remain compatible; prefer explicit @type declarations in new scripts.
secret masks input; it does not encrypt stored values. Using Set as default persists the actual content. Printing the value or embedding it in source can also expose it.
You do not need to classify scripts as adb commands. The editor has no auto / use / none selector. Before execution, the plugin attempts to read the single online, usable Android device selected in the current project's IDE run toolbar. When available, its serial becomes the child process's ANDROID_SERIAL.
Ordinary scripts do not require Android devices. If the Android plugin is missing or disabled, its selection API is incompatible, no device is selected, a device is offline, or multiple devices are selected, no automatic serial is injected and ordinary scripts can still launch. Selecting a device alone does not add an adb dependency.
- Connect and authorize the device in Android Studio or an IDE with a compatible Android plugin.
- Select one device in the current project's run toolbar.
- Install and configure adb or scrcpy when your script uses them.
- Run the script. The console reports the default device serial when one was obtained.
To require an IDE-selected device, declare adb, android_device in Required tools, or set a template-referenced parameter to kind: "android_device" with required: true. These explicit requirements block execution without a valid selected device. An optional device parameter is empty when none is available.
Selection is read at the start of the run. Changing it during execution does not update the running process. A script's explicit ANDROID_SERIAL overrides the automatic value; adb -s SERIAL follows adb's own targeting rules. Without an automatic serial, external tools use inherited environment values and their own device rules, which may succeed or report missing/multiple devices. The plugin does not scan/connect devices or restart adb services.
The legacy JSON field android_device_mode remains compatible with storage/import but no longer controls execution.
- The current project's Run tab displays stdout, stderr, an exit code, and the output directory. It does not automatically print the startup command line containing the script body.
- A script reuses its tab by ID, including after a rename. A new run clears the previous output.
- Clicking a script again while it is starting or running focuses its existing console without launching a duplicate. Different scripts can run concurrently.
- 再次运行 (Run again) uses the IDE’s standard green triangle icon and reads the latest saved definition and initializes the form with the previous inputs.
- 停止 (Stop) and timeouts terminate the run and traceable child processes, without stopping shared adb services. Detached programs are not guaranteed to remain traceable.
- Process stdin is closed. Interactive menus and runtime password prompts are unsupported; use pre-run parameters or noninteractive tool options.
Each execution creates a temporary output directory, exposes it as POPTOOLS_OUTPUT_DIR, and prints its path in the console. Ordinary echo and print output stays in the console and does not create files automatically; scripts may explicitly save reports or other generated files there. Temporary Python/batch source files and empty output directories are deleted after exit; nonempty output directories are retained. These directories are in system temporary storage and may still be cleaned by the OS. Copy results to your project or another chosen location for long-term storage.
Use 分享脚本 (Share script) to copy JSON. The recipient copies the complete JSON and clicks 导入 (Import). Accepted clipboard formats are:
- A v1
poptools.custom-scriptshare envelope; - A raw v1 custom tool object;
- An array of tool objects;
- An object containing a
scriptsarray.
Sharing removes the interpreter override, parameter defaults, and inline template defaults, while preserving explicit types and dropdown/radio options. Literal content in commands/environment values and paths outside defaults remain present; inspect the actual content before sharing. External script files are not copied by clipboard sharing.
When an ID or title conflicts, choose 覆盖 (Overwrite) to retain the existing ID, 另存 (Save separately) for a new ID and unique title, or 跳过 (Skip). Imports report success, skips, and failures per item; one failure does not roll back successful items. Unsupported fields, kinds, and versions are rejected. internal and url executors are unsupported. PopTool-managed environments and internal resource paths need adjustment for the IDE.
Minimal importable example:
{
"schema_version": 1,
"id": "custom.hello",
"title": "Hello Python",
"description": "Print a greeting",
"executor": {
"kind": "python",
"command": "print('Hello from NikoTools')"
}
}Use 批量操作 → 导出目录 (Batch operations → Export directory) to choose a destination. The plugin creates a new timestamped directory:
poptool-scripts-<timestamp>/
├── tools/ # Script JSON, including defaults
└── scripts/ # Transferable external script files, if present
For 导入目录 (Import directory), select the export root. The importer prefers its tools subdirectory and searches JSON files recursively. Directory files should contain a single tool/share object or an array of tools; use clipboard import for a scripts wrapper. Before import, the current library is backed up under poptool-backups/<timestamp> in the IDE configuration directory. Source files are not modified.
For recognized direct references to absolute .py/.ps1/.sh/.bat/.cmd files, export copies the containing directory's files and rewrites the entry to a relative path. Import of transferable relative entries copies resources into poptool-assets in the IDE configuration directory and updates the entry path. Symbolic links are skipped. Dynamic references, resources elsewhere in the project, extra tools, and interpreter paths require separate migration; directory export is not a complete project archive.
Directory exports and automatic backups preserve defaults and suit backup/machine migration. Clipboard sharing removes defaults and suits sharing definitions. Reconfigure tool paths on the destination machine.
Type: python. Body:
import pathlib
import sys
path = pathlib.Path(sys.argv[1])
print(path)
print(path.stat().st_size)Arguments JSON:
["${input@file}"]Type: bash. Body:
printf 'Directory: %s\n' "$1"
ls -la -- "$1"Arguments JSON: ["${directory@dir}"]. A path with spaces remains one argument.
Type: powershell. Body:
var message = ${Message:Hello}
var mode = ${Mode:On=1|Off=0}
Write-Output '${message}'
Write-Output '${mode}'This demonstrates literal substitution. Adjust string handling if the message contains single quotes.
Type: process. Body: adb. Arguments JSON: ["devices", "-l"]. Listing devices does not require an IDE-selected device. To read a property from the selected device, use ["shell", "getprop", "ro.product.model"]; the injected ANDROID_SERIAL supplies adb's default target. Add the android_device requirement if an IDE-selected device is mandatory.
Type: bash. Body:
var verbose = ${Verbose:False}
printf 'Argument: %s\n' "$@"Arguments JSON: ["?verbose:--verbose"]. Save, then edit verbose metadata to set kind to boolean. Checking the box adds --verbose; leaving it unchecked omits the argument. This demonstration only prints its arguments. For a real tool, replace the printing command with an invocation such as mytool "$@".
| Symptom | What to check |
|---|---|
| Interpreter/tool not found | Installation, IDE PATH, and global paths; correct or clear an invalid explicit path |
| Works in terminal but not in plugin | IDE startup environment, virtual environment, working directory, and execution type |
process cannot find git status
|
Put only git in the body and move arguments to the JSON array |
| Working directory does not exist | Default is the current project root; relative directories resolve from that root |
| Android device missing | Ordinary scripts can continue; required-device scripts need one online authorized selection and a compatible Android plugin |
| File browser enters folders | Normal navigation; use @dir for directory input and @file for file input |
| Garbled output | Match Output encoding to the external tool; Python is configured to request UTF-8 |
| Parameter/JSON errors | Use valid JSON with double quotes and correct arrays/objects; check conflicting declarations and numeric input |
| Quotes in input break source | Substitution does not escape input; use Arguments JSON or handle target-language quoting |
| Script waits for input | Runtime stdin is unavailable; use pre-run forms or noninteractive options |
| Terminal context action missing | Enable Terminal and select text; the terminal implementation must expose a compatible selection API |
| Another project shows the same scripts | The IDE library is shared; execution context still belongs to the current window |
Scripts and paths are persisted in options/poptool-scripts.xml under the IDE configuration directory, not in the project. Backups use poptool-backups; imported resources use poptool-assets. Separate IDE configuration directories do not automatically share libraries; use directory migration.
The implementation uses Kotlin and the official Kotlin UI DSL; the current UI labels are Chinese. See the project README for builds, tests, compatibility verification, and Marketplace publishing. The bilingual Overview is maintained in plugin.xml, in description. Rebuild and install to view the local description; the Marketplace listing updates when the new package is published.
Plugin source and template resources use the MIT License. IDEs and external tools retain their own licenses.