Using the Terminal

The terminal runs the same commands the JSlope interface runs for its edits. A line typed in the terminal and the equivalent clicks give the same model, the same undo step and the same results, so you can mix the two freely.

Use it to enter exact coordinates and properties, to repeat a sequence of edits, to read results and settings back as text, or to record a modelling workflow as a command script.

Opening the terminal

The terminal is open when JSlope starts, docked below the model view. The view shrinks to make room, so Fit and the drawing tools keep working above it. Drag the divider to resize it. To hide or show it, use the small square in the bottom-left corner of the model view, View > Terminal, or Ctrl+` (⌘` on macOS). The × button in the terminal also hides it.

The terminal remembers its height and whether you last used the Console or Script tab.

Typing a command

The Console tab runs one command per line. A line is a command name followed by name=value arguments:

cad.line.add from=[0,0] to=[12,4]
material.add id="clay" name="Stiff clay" properties={"unitWeight":19,"cohesion":12,"frictionAngle":24}
analysis.lem.run

Each value is a JSON literal:

Separate arguments with spaces, and do not put spaces around =. Arguments can come in any order. Lines starting with # are comments. A Console line holds one whole command; in a script a long array or object can continue onto the following lines.

Lengths are in metres, angles in degrees, stresses in kPa and unit weights in kN/m³, as in the rest of JSlope. Coordinates are model coordinates: x to the right, y up. Transient groundwater times, such as stage times and time-function points, are in the scenario's time unit (days unless you change it), as in the Groundwater dialogs.

Ids

Commands that create something take an optional id argument, such as cad.line.add id="crest-line" .... Later commands use it to refer to the object: cad.object.move ids=["crest-line"] delta=[0,2]. An id starts with a letter and contains letters, digits, _, ., : or -, up to 64 characters. When you leave it out, JSlope generates one and reports it in the output.

Most commands name the new object's id id. A few create more than one thing, or something other than their main object, and name those ids differently:

• anisotropy.field.add takes lineId for its control line.
• water.table.set keepPrevious=true takes previousId for the kept line. water.table.fromGroundwater takes id for the construction polyline it adds: the new line with as="polyline", or the kept Previous Water Table with keepPrevious=true.
• cad.construction.convert takes newId, and cad.segment.delete, domain.segment.delete and geometry.trim take newId for the second piece when a line splits.
• cad.paste takes ids and cad.duplicate takes newIds, one per copy.
• group.create takes masterId for the group's Master Scenario, and group.duplicate takes scenarioId for the first copied scenario.
• section.apply newGroup=true, parametric.applyBatch and parametric.sweep take groupId and masterId.

When clipping cuts a new boundary or tension crack into pieces, the first piece keeps the id and the others get -2, -3 and so on. For example, material.boundary.add id="mb-clay" ... that is cut in two creates mb-clay and mb-clay-2. These ids stay the same when you later edit the External Boundary, undo or redo, switch scenarios or reopen the project.

Ids belong to the active scenario, except scenario, group, Rock and Rock Source definition ids, which belong to the whole project. A command that names an id the model does not have is refused before it changes anything, with a message such as cad.object.move: ids: No CAD object has id "crest". When a command is refused because of one argument's value, such as an id that is already used or a segment or vertex index the object does not have, the log names that argument.

Argument guidance while you type

As soon as a line names a command, the terminal shows how to write it:

• The first line is the command's usage. Required arguments are listed plainly, optional ones in brackets, and each shows the kind of value it takes, such as from=<point m>, magnitude=<number kPa> or type=<"aligned"|"horizontal"|"vertical">.
• The argument you are typing, or the next required one, is bold and underlined. Arguments already on the line are dimmed.
• The second line explains that argument, how to write its value and an example, for instance to (required): End point [x, y]. Value: [x,y] in m, e.g. to=[2,2]. For a choice of values it lists the choices.
• Inside a JSON object, such as compute={...}, the guidance names the key at the caret by its full path, such as groundwater.groundwaterSetup.timeUnit, with its unit and allowed values.

The same guidance appears under the Script tab for the line holding the caret. If a command cannot run at the moment, for example because an analysis is running, the guidance says why.

Completing and recalling commands

• Tab completes command names, argument names, listed values and the ids of existing objects. Ids are listed with their names, such as clay shown as Stiff clay (material). Inside a JSON object, Tab also completes the object's keys and their listed values. With several matches it fills in their common start or opens a list; use ↑ and ↓ to choose, Enter to accept and Esc to close the list. Tab moves focus as usual when there is nothing to complete.
• ↑ and ↓ with no list open step through earlier commands. The line you were typing comes back when you step past the newest one. The history keeps about 200 lines and is still there after you reload JSlope in the same browser.
• Ctrl+R searches the history. Type part of a command to filter it, newest first; ↑, ↓ or Ctrl+R move through the matches. Enter or Tab puts the match in the prompt without running it, and Esc cancels the search.
• Enter runs the line.
• Pasting several lines into the prompt does not join them into one. The prompt offers Send to Script, which adds them to the end of the Script tab, or Discard. While a script runs, Send to Script waits: a notice says so and the offer stays until the script ends. A single copied line goes in as it is, without its line break.

Picking points and ids from the model

While the Console prompt or the Script editor has the keyboard focus:

• Alt+click on the model inserts the point under the cursor as [x,y] in metres at the caret. A snapped point is exact to 6 decimals; otherwise the point is rounded to the screen resolution.
• Alt+Shift+click inserts the id of the object under the cursor, such as "line-1".

Inside an open array JSlope adds the comma before the value, and after a word it adds a space, so you can click several points in a row: cad.polyline.add points=[ then three Alt+clicks gives cad.polyline.add points=[[0,0],[12,4],[20,4]. A pick only inserts text: it does not select, edit or run anything, and it works while a script runs. When the terminal does not have focus, Alt+click keeps its usual meaning of placing a point without snapping.

Help

For an argument that takes a JSON object, help <command> also prints a Keys of table for the object, and for each object inside it, listing every key with its unit and allowed values. help scenario.settings.apply, for example, lists every key of compute, advanced, groundwater, stress, rockfall, runoutSimulation and runoutVolumetric.

The areas follow the model: CAD objects, domain geometry, materials, loads, supports, water, scenarios, settings, analyses (LEM, FEA, Rockfall and Runout), queries, results, scripts, project files and server runs. help always lists the commands of the version you are using.

Output and undo

Each command is echoed with ›, followed by its result: ✓ with a message and the ids it created, changed or deleted; ✗ with the reason it did not run; or – when it was stopped. Queries such as model.list, material.list, analysis.status and the result and read-back queries print their answer below the result; history.status gives its answer in the ✓ message itself. Analyses and file imports also print a short report below the result, such as the scenario and method table of a Compute All.

Every successful model edit is one undo step, exactly like the GUI edit it replaces, and the history keeps the last 20 steps. Undo with history.undo, the toolbar or Ctrl+Z in the model view. Keys typed inside the terminal stay in the terminal: Delete, Backspace and Ctrl+Z edit the command line, never the model.

Settings objects accept only the keys help lists. A misspelt key, an unknown choice or a value out of range is refused with the valid keys and a suggestion, and nothing changes:

› scenario.settings.apply stress={"elasticStressMode":"plane_stress"}
✗ scenario.settings.apply: stress.elasticStressMode: "plane_stress" is not one of "plane-strain", "plane-stress". Did you mean "plane-stress"?

Choosing the WebGPU backend for stress or groundwater is refused when this browser has no WebGPU, rather than silently running on the CPU.

Running analyses

Analyses such as analysis.lem.run wait for their result and report it. On a transient groundwater scenario analysis.lem.run computes the factor of safety of the initial state and of each stage marked Calculate FOS.

While an analysis started from the Console or a script runs, a progress row in the log shows its percentage, message and stage, and for LEM the best FOS so far. It updates about once a second. When the analysis ends the row settles and drops its bar, leaving the label and last message above the result. This covers analysis.lem.run, analysis.rockfall.run, fea.groundwater.solve and fea.stress.solve. A transient fea.groundwater.solve shows a Groundwater solve row for the hydraulic run, then a Groundwater Solve row for the stage factors of safety. runout.prepare and runout.run have no known end, so their row shows the particles packed and the time simulated and steps taken, without a percentage. runout.volumetric.compute waits for failure volume and catch capacity without preparing particles or running physics; its progress is indeterminate. runout.particles.clear removes the active scenario's particles and physics results while preserving volumetrics. Automatic packing stays off until an explicit runout.prepare or runout.run. server.run.apply and cad.image.import show no row: the download and the image read report no progress. Analyses started from the GUI show their progress in their own dialogs.

Remove Volumetrics (runout.volumetric.clear) clears the active scenario's volumes, capacity polygon, projected line and volumetric warnings while retaining particles and physics measurements. Live volumetric updates remain paused for that scenario during the project session until Compute Volumetrics, Prepare or Simulate is explicitly started. Removal is unavailable during computation or Tank mode.

While a command or script runs you can keep typing, and Enter still runs help, clear, queries and control commands at once, beside the running command:

analysis.status
analysis.pause
analysis.resume
analysis.cancel mode="keep"

Any other line is not run. A notice asks you to wait or use Stop, and the line stays in the prompt so you can send it later.

Stop cancels any open file prompt and asks the running command to stop. What happens next depends on the command, and help <command> says which:

• Analyses (analysis.lem.run, analysis.rockfall.run, fea.mesh.generate, fea.groundwater.solve, fea.stress.solve) and Runout (runout.prepare, runout.run, runout.volumetric.compute) stop and discard their partial results.
• Project file commands (project.new, project.open, project.save, the imports and project.export.results) stop only until they start writing or replacing the project; after that they run to the end.
• cad.image.import stops only while its file prompt is open.
• server.run.apply, server.run.cancel, server.runs.list and result.export cannot be interrupted; Stop waits until they end.

analysis.cancel mode="keep" stops an analysis and keeps its best result so far. It is refused for Rockfall and Runout, for an LEM search that has not yet found a valid surface, and for LEM and groundwater runs on the JWG server, which analysis.cancel stops without keeping a result.

analysis.pause and analysis.resume pause and resume an LEM, groundwater or stress solve running on this device, and Rockfall running Native on a JWG Compute host that offers pause. They are refused, with a message naming the operation, for Browser and Cloud Rockfall, Runout, mesh generation, project file commands, server result downloads and runs on the JWG server. What counts is where the work running at that moment executes, not the switch alone: Compute All with a transient scenario enabled searches its other scenarios on this device even with LEM set to the JWG server, so those searches can be paused and stopped with mode="keep". While an LEM run is solving a prerequisite, such as a groundwater solve on the JWG server, a pause that the prerequisite cannot take is refused with its message.

Where analyses run

compute.location.set chooses whether LEM (including scenario batches), Rockfall and groundwater analyses run on this device or on the JWG server, as the switches in Project Settings > Compute do:

compute.location.set lem="server" groundwater="server"
compute.location.set lem="device"

It is a preference of this browser, not part of the project, and adds no undo step. It is refused while an analysis runs, and, from the Console or the GUI, while a script runs, since the analyses still to come read it. A script's own compute.location.set lines run. While it is refused, the Project Settings > Compute switches are disabled with the reason, and an Apply that changes them is refused as a whole, with the dialog left open. Changing a switch and selecting Apply adds the matching compute.location.set line to the Console, marked GUI, and a saved session keeps it, so a script made from those lines runs its analyses in the same place on another device. analysis.status reports where each analysis runs. The Server runs commands list, cancel and apply server runs.

The output log

• Selecting and copying rows copies the command lines themselves, without the › sign, the GUI marker or line labels. Result rows between commands are copied as they appear.
• Save session as .slope (beside the close button) saves every command you typed in the Console and every GUI command, in order, each followed by its result as a # ok: … comment. Commands that failed or were cancelled are written as comments (# failed, not replayed: …), and so are queries and control commands typed while another command ran (# ran during another command, not replayed: …), since replayed they would find nothing running. help and clear are not included, and neither are script lines: where a script run applied commands, a comment such as # Script run (lines 1–40, 38 commands applied) not included marks the place. The file replays cleanly on the model it started from, once any marked script runs are replayed at their places.
• Send GUI lines to Script adds the GUI commands that succeeded, and that were not sent before, to the end of the Script tab and switches to it.
• The log keeps the latest 1,000 entries. When older ones are dropped, a note at the top of the log says how many.