Importing and sharing setups
Portable file reference
A .terminalis file is a strict UTF-8 YAML snapshot. Use it for terminal definitions that should be reviewed, versioned, and copied into a local Terminalis setup.
Document structure
The current export version is 2. Choose kind: terminal with one terminal, or kind: tag with a nonblank tag and ordered terminals list. Do not combine the two shapes or add unrelated top-level metadata.
This complete single-terminal example runs only pwd when you explicitly select its command:
version: 2
kind: terminal
terminal:
id: web
displayName: Web
description: Demo frontend shell
cwd: web
env:
APP_ENV: development
command:
- id: inspect
name: Inspect directory
run: pwd
This complete collection creates a shared tag and three terminal definitions. Create the listed project folders before running its commands:
version: 2
kind: tag
tag: demo
terminals:
- id: web
displayName: Web
cwd: web
command: pwd
- id: api
displayName: API
cwd: api
env:
PORT: "8080"
command:
- id: inspect
name: Inspect API
run: |
printf 'API demo\n'
pwd
- id: worker
displayName: Worker
cwd: worker
command: pwd
An empty tag terminal list is valid, but creates no profiles or visible empty tag. Import does not execute any of these scripts.
Terminal fields
| Field | Required | Meaning |
|---|---|---|
id | Yes | Stable lowercase letters/digits with internal hyphens; unique in the file. No leading or trailing hyphen. |
displayName | Yes | Nonblank name shown in the app; can change without changing identity. |
description | No | Text preserved through import/export; does not affect execution. |
cwd | No | Relative to the import project root, or an explicit POSIX absolute path. Omission means the project root. |
env | No | Map of variable names to strings or version-2 stored values. |
requiredEnv | No | List of variable names required before attached commands run. |
command | No | A script string, command mapping, or ordered list mixing both. |
Paths use /; they cannot contain .. segments, Windows drive/UNC prefixes, backslashes, NUL, leading ~, or variable interpolation. . and blank optional paths mean the surrounding directory. Relative paths are checked through existing ancestors to prevent symbolic-link escape from the import root.
Environment names use shell-variable syntax and cannot assign the reserved TERMINALIS_ prefix. Quote values that YAML might interpret as numbers, booleans, dates, or null. References such as $PATH and ${DEMO_ROOT} are preserved for later dependency expansion; cycles are rejected.
For version 2, a hidden value can be a mapping with value and storage: xor1. Generate it with the editor's Hide control and export; do not substitute the plaintext into an encoded field. It is reversible obfuscation.
Command fields
| Field | Required | Meaning |
|---|---|---|
run | Yes for a mapping | Nonblank script; internal newlines are preserved. |
id | No | Starts with an alphanumeric character, then uses alphanumerics, ., _, or -; unique among this terminal's commands. |
name | No | Friendly selector label. |
cwd | No | Relative to the terminal directory or a POSIX absolute path. |
run_in_current_directory | No | Boolean; when true uses the live shell directory and cannot be combined with cwd. |
env | No | Command-only environment values, with the same value rules as terminal env. |
requiredEnv | No | Additional names required for this command. |
hide_command | No | Boolean; print a compact label instead of the full submitted script. Output stays visible. |
A command list is a set of alternatives, not a sequence. Use a multiline run value for one script with several lines. Duplicate command IDs are invalid. Identical scripts with differing metadata need distinct IDs so they remain distinguishable.
Terminal and command requirements are combined before an attached run. Name only in export creates requirements without values; import does not retrieve those values for you.
Versions and limits
Version 1 remains readable but accepts only scalar string environment values. New exports use version 2. The portable parser rejects compatibility aliases and unknown fields even where the app-owned local configuration parser is more permissive.
| Limit | Maximum |
|---|---|
| File size | 2 MiB |
| YAML documents | Exactly one |
| Nesting | 64 levels |
| Expanded nodes | 100,000 |
Duplicate mapping keys, custom YAML tags, merge keys, unsupported versions, malformed IDs, invalid environment values, and unsafe paths are rejected. The format excludes personal tags outside the exported tag, startup preferences, history isolation, global commands, runtime state, output, and history.
Files do not install dependencies, discover repositories, order services by readiness, rewrite script paths, sandbox execution, or redact output. Review commands before running them. For update identity and preserved local state, see Update an import.