Skip to content
DiagravoDocsOpen editor

Docs The terminal

The terminal

A command line built into the editor: build, change and inspect a diagram by typing it, and run the same actions as the menus.

Opening it#

Press Ctrl+` (Cmd+` on a Mac) from anywhere, or choose View → Terminal. The bottom panel opens on the Terminal tab with the cursor in the prompt. Type help to list the commands, or help connect for one of them, and insert sample to put a small example app in the prompt to read, change and run.

Open an example diagram, then try dump in the terminal

The language#

Every line is a command: a verb, then what it applies to. Press Enter to run; Shift+Enter adds a new line so you can write a multi-line script and run it all at once.

# a client, three backends behind a load balancer, one database
add client web activeUsers=200
add 3 backend api requestsPerSec=500
add lb balancer
add database db engine=postgres
connect web -> balancer
connect balancer -> api-*
connect api-* -> db
  • Ids. Components are referred to by id (web, api-2). Leave the id off and one is picked: backend-1, backend-2…
  • Types. Use the type’s name or a short name — lb, db, s3, gateway, lambda… Spaces, hyphens and capitals are ignored (load balancer works). types prints every one, and the component tables list them too.
  • Settings. name=value pairs, case-insensitive: vcpu=4 ramMb=1024. Choices are matched loosely (engine=Postgres).
  • Chains and lists. connect a -> b -> c draws every link. connect lb -> api-1, api-2 fans out.
  • Wildcards. A * at the end of an id matches any ending: api-* is every component whose id starts with api-.
  • Position. add backend api at 400 200 places it; without at, new components are laid out for you.
  • Comments. Everything after # on a line is ignored. Use quotes for a value with spaces.

It is safe to experiment#

  • All or nothing. A script runs on a scratch copy first. If any line has a problem — a typo, an unknown id, a value out of range — nothing is changed, and the error points at the line and column, with a “did you mean” where there is an obvious candidate.
  • One undo step. A script that works is a single change: Ctrl+Z undoes the whole thing.
  • Same rules as everywhere. The result is checked against the same rules as the canvas and the JSON panel, and view-only collaborators cannot run commands that change the diagram.
  • Round trip. dump prints the current diagram as a script. Run it on an empty canvas (or paste it into another diagram) to recreate it exactly.

Keys in the prompt#

Terminal prompt keys
KeyWhat it does
EnterRun the script.
Shift+EnterNew line (build a multi-line script).
TabComplete the word under the cursor — verbs, types, ids, settings and values. Press again to cycle through the options.
↑ / ↓Step through earlier scripts.
EscClear the prompt; press again to leave it.
Ctrl+LClear the log.

Command reference#

This page is generated from the terminal’s own command table, so it always lists exactly the commands that exist.

Commands that change the diagram#

Each one is undoable, and a whole script of them is a single undo step.

add#

Add components.

add [count] <type> [id] [attr=value …] [at x y]
  • The id is optional — leave it out and one is picked (backend-1, backend-2…).
  • With a count, an id works as a prefix: add 3 backend api makes api-1, api-2, api-3.
  • Without at x y, new components are laid out for you, below what is already there.
  • Type types to see every component type and its short names.
add backend
add client web activeUsers=200
add 3 backend api requestsPerSec=500
add database db engine=mysql at 400 200

connect#

Draw connections. Also: link.

connect <from> -> <to> [-> <next> …] [direction=…] [order=…]
  • A chain draws every link in it: connect web -> api -> db.
  • Lists fan out: connect lb -> api-1, api-2. A * matches any ending: connect lb -> api-*.
  • Connecting what is already connected is quietly skipped.
connect web -> api -> db
connect lb -> api-*
connect a -> b direction=both

disconnect#

Remove connections. Also: unlink.

disconnect <from> -> <to>  |  disconnect <id>
  • With just one id, every connection touching it is removed.
disconnect web -> api
disconnect cache-1

remove#

Delete components (and their connections). Also: rm, delete.

remove <id> [id …]
  • A * matches any ending: remove api-*.
remove cache-1
remove api-*

set#

Change components' settings.

set <id> [id …] attr=value [attr=value …]
  • Applies to every id listed (or matched by *). Names are not case-sensitive.
  • Enum values are matched loosely: intent=ddos, engine=Postgres.
set api requestsPerSec=500
set api-* vcpu=4 ramMb=1024
set web intent=ddos activeUsers=5000

rename#

Change a component id (connections follow).

rename <id> <new id>
rename backend-1 api

layout#

Re-arrange every component automatically.

layout
  • Undoable like everything else. Not available for diagrams that use groups yet.
layout

snap#

Snap everything to the grid.

snap
snap

clear#

Remove every component and connection.

clear
  • Undoable — Ctrl+Z brings everything back.
clear

Commands that show things#

These never change the diagram.

insert#

Put a small example app in the prompt.

insert sample
  • Types a client, two backends and a database (already connected) into the prompt so you can read it, change it, and press Enter to run it.
  • Safe to do more than once — new names are picked if the old ones are taken. Run it on its own, not inside a script.
insert sample

list#

List components and what they connect to. Also: ls.

list [type]
list
list backend

focus#

Centre and zoom the view on a component.

focus <id>
  • A * matches any ending and frames all of them: focus api-*. Double-clicking a component on the canvas does the same.
focus api
focus api-*

show#

Print one component's settings and connections.

show <id>
show api

dump#

Print the diagram as a script that rebuilds it.

dump
  • Paste the output back (or into another diagram) to recreate it. Groups are not included yet.
dump

types#

List every component type and its short names.

types
types

help#

Show the commands, or details for one. Also: ?.

help [command]
help
help connect

fit#

Zoom to fit the whole diagram.

fit
fit

Commands that run app actions#

The same actions as the toolbar and menus. If one is not available right now, the terminal says so.

play#

Start playback.

play
play

pause#

Pause playback.

pause
pause

stop#

Stop playback.

stop
stop

mode#

Switch playback mode.

mode default | rule
mode rule

script#

Show or hide the Script (JSON) panel. Also: json.

script [show | hide | toggle]
  • With no argument it toggles. json works too. The panel can also be opened from View → Script panel.
script hide
script show
script

drawer#

Collapse the components drawer to icons, or expand it. Also: components.

drawer [expand | collapse | toggle]
  • With no argument it toggles. Collapsed, the drawer is a narrow rail of icons you can still drag from.
drawer collapse
drawer expand
drawer

save#

Save the diagram (on this device, and to the cloud when signed in).

save
save

publish#

Publish a share link.

publish
publish

share#

Open collaboration sharing.

share
share

import#

Import a JSON file.

import
import

templates#

Open the template gallery. Also: template.

templates
templates

export#

Export the diagram.

export json | png | gif | video | code
  • gif and video are only available in Rule-based mode.
export png
export code

Undo and redo#

Run these on their own, not inside a script with other commands.

undo#

Undo the last change.

undo
  • Run on its own, not inside a script with other commands.
undo

redo#

Redo.

redo
  • Run on its own, not inside a script with other commands.
redo

Last updated . Something unclear or out of date? Tell us.