ISSCROLLS(1) General Commands Manual ISSCROLLS(1)

isscrolls — Player toolkit for the Ironsworn Family Tabletop RPG

isscrolls [-bcx]

isscrolls is a toolkit for players of the Ironsworn tabletop RPG. It supports classic Ironsworn, Delve, Starforged, and Sundered Isles. It is intended for both solo and co-op play and allows tracking your character's progress including vows, roll on adventure and exploration moves, tracks progress for fights, journeys, and expeditions and provides results from the static oracle tables from the official rulebook. The options are as follows:

Suppress the banner on startup.
Enable colors and additional characters to beautify output. Recommended if you don't use a screen reader or a braille terminal.
Roll a “cursed die” alongside the other dice. This is a speciality of the Sundered Isles expansion, however, it can be used for the other games as well.

isscrolls basically works like a Unix shell. Commands can be entered and will show their output. Certain commands need an argument in order to run properly, other commands might support optional arguments. Once a character is loaded, the prompt will change and display the character's name. The help command will show an overview of all available commands.

isscrolls is linked against readline(3), thus any shortcut or character combination that work with a common Unix shell also work for the built-in shell.

isscrolls supports all games of the Ironsworn family and allows players to freely use moves or actions from all of them. Therefore, depending on the game you own you might see statistics or information that belong to another game, e.g., characters get experience points in classic Ironsworn for fulfilling vows while in Starforged they get experience via the so called . Both ways are supported by isscrolls so choose the one that fits your game the most.

Sometimes isscrolls cannot take a decision for you and refers you to the official rulebook. In these cases choose the outcome most suitable for your character and manipulate the stats with the increase, decrease or toogle commands. See the section below for more information how the commands work.

isscrolls is best used if you generate a character with the create command and load it afterward with the cd command. Once you load a character, their current stats will be printed which looks similar to the following:

Name: Erin Kalina (Exp: 7/30) Exp spent: 4

Edge: 4 Heart: 3 Iron: 2 Shadow: 2 Wits: 3

Momentum: 10/10 [2] Health: 4/5 Spirit: 5/5 Supply: 3/5

Wounded:        0 Unprepared:   0 Encumbered:   0 Shaken:       0
Corrupted:      0 Tormented:    0 Cursed:       0 Maimed:       1

Bonds: 0.00 (L: 0) Quests: 0.00 (L: 0) Discoveries: 0.00 (L: 0)

The first line shows the character's name, their experience points, the amount of experience points spent to acquire new resources or improve existing ones and their failure track in ticks in case the character has rolled more than one miss.

The second line shows the character's stats and the third one the current values. The number in the square brackets after is the reset momentum.

Debilities are shown in the next two lines, a 0 means that the character does not suffer from this particular debility while a 1 means that they suffer from it.

The last line shows the character's progress for bonds, quests and, discoveries including the progress on the legacy tracks.

As soon as a character starts one of them, the prompt changes and displays the current undertaking and the current progress.

Progress will be tracked automatically according to the rank. For lower ranks (Troublesome - Formidable), progress will be shown as absolute numbers, e.g. a 2 represents two boxes. For higher ranks (Extreme and Epic), progress will be shown as decimal numbers and 0.25 represents one tick, e.g. 0.75 means that the character already made 3 ticks progress. Since progress bar is always 10 boxes, only the current progress is shown.

In case the rulebook gives you more options, you always have the possibility to manually mark progress with the markprogress command. In case you have an active vow, its title and description will be shown.

It is possible to create notes for future reference.

It is also able to write entries to a journal file.

can be turned on to automatically journal some commands and their results, such as the results of random actions.

The following sections shows all commands that can be entered on isscrolls command prompt.

This subsection shows general commands that are not dice rolls and game moves.

[name]
Load the character [name], if it exists. If [name] is not provided and a character is loaded, the character is saved and unloaded.
Show an overview of all available commands.
List all available characters.
Quits isscrolls and saves all characters, journeys, fights, delves, vows and the command line history.
Saves the current character including an active vow, journey, fight, or delve.
Starts autojournalling. When autojournalling is on, some commands and their results will be written to the journal file.
Stops autojournalling.
text
Writes text as an entry to a journal file. This command can be abbreviated to 'j'.

The file will be in the isscrolls directory. There will be a separate file for each character. If the current character is deleted and a new character is created with the same name, a new journal file will be created.

The following commands can be used to roll dice according to the game's mechanics. They can be used since isscrolls does not provide commands for all moves in the game.

stat [bonus]
Roll one action die and two challenge dice. Providing one number as stat is mandatory. Provide an optional [bonus].
Roll one challenge die.
Roll one oracle die.
Mark a bond. Usually, this is done automatically if you have a strong hit on the forgeabond move. On a weak hit, consult the Rulebook first and then use this command.
Mark progress according to the rank. isscrolls progresses the undertaking in the following order:
  1. Fight
  2. Delve
  3. Journey
odds
Roll two challenge dice to get an answer to a yes/no question from the oracle. odds has to be a number (1-5) of the following list:
  1. Almost certain
  2. Likely
  3. 50/50
  4. Unlikely
  5. Small chance
Burn your character's momentum and set it to the reset momentum.

The following commands can be used to modify your character. isscrolls supports multiple characters, however, only one can be loaded at a time. Most commands do nothing or present a warning if no character is loaded.

[name]
Create a new character. If the optional argument [name] is provided, it will be used as the character's name. Otherwise, the name will be asked interactively.
stat
Decrease the character's value stat. You can also decrease the progress of a fight or a journey. Hereby, the progress is automatically decreased according to the rank. You can also decrease the progress of or the quest, discovery and failure track.

To give the player a bit more flexibility, this allows to decrease values even if this is forbidden by the official rulebooks.

The following values can be decreased:

  • Edge
  • Heart
  • Iron
  • Shadow
  • Wits
  • Momentum
  • Health
  • Spirit
  • Supply
  • Exp
  • Expspent (the experience you spent to acquire new resources or improve existing ones).
  • Weapon (hereby means a simple weapon doing 1 harm and means a deadly weapon doing 2 harm).
  • failure (progress on the failure track)
  • quests (progress on the quests (vows) track)
  • discoveries (progress on the discoveries track)
Delete the current character without warning!
stat
Opposite of the decrease command described above.
Print the current character's stats.
stat
Toggle a character's stat named stat. If it's set to 0, it will be set to 1 or vice versa. The following values can be modified.
  • Wounded
  • Unprepared
  • Shaken
  • Encumbered
  • Maimed. Note that this is a permanent bane and cannot be changed once it has been set.
  • Cursed. Note that this is a permanent bane and cannot be changed once it has been set.
  • Corrupted
  • Tormented

The following commands let you manage vows. Additional vow related commands can be seen below in the Quest Move section.

Compared to swearanironvow, this command just saves a new vow and does not roll the die. It is meant to be used to save the character's initial vows.

You will be asked for a title - which is like a short description of the vow - and a longer description. The prompt changes and shows the title of the active vow and the current progress.

id
Activate the vow id, with id being a number between 1 and 255. Every vow has a unique number that can be seen with the vowshow command. Activating a vow means that the prompt shows the title and certain moves will influence it.
Opposite command which deactivates the current vow. Certain vow related commands will not work.
Shows the character's vows including the following details:
  • ID that can be used with vowactivate and vowdeactivate
  • Title of every vow
  • Current progress
  • The rank
  • Fulfillment status. 0 means unfulfilled, 1 means fulfilled.

The following commands let you manage 'sticky' notes.

Creates a 'sticky' note. Every note has a unique number that can be seen with the noteshow command. Each note must have a title and a description.
id
Edit an existing note. Modify the title and description.
Shows the character's notes including the following details:
  • ID that can be used with noteedit and notedelete.
  • Title of every note
  • Description of every note
id
Deletes an existing note.

Adventure Moves are used as your character travels the Ironlands, investigates situations and deals with threats. Exploration moves are the same concept, however, the new name was introduced with Ironsworn Starforged.

stat [bonus]
Roll a Face Danger move using the character's stat named stat. This move can be done using the following stats: edge, heart, iron, shadow, and wits. An additional [bonus] can be provided.
stat [bonus]
Roll a move using the character's stat named stat. This move can be done using the following stats: edge, heart, iron, shadow, and wits. An additional [bonus] can be provided.
[bonus]
Roll a move. Provide an optional [bonus].
who [bonus]
Roll a move. If the character wants to heal themselves, the argument me has to be provided. isscrolls automatically selects the character's Iron or Wits, whichever is lower. If the character wants to heal someone else, the argument others has to be provided. An additional [bonus] can be provided.
Roll a move.
[bonus]
Roll a move. An additional [bonus] can be provided.
[bonus]
Roll a Make Camp move.
Roll an move Note that a strong hit with a match provides you with a different result..
[bonus]
Roll an move. Provide an optional [bonus].
stat [bonus]
Roll an Undertake an Expedition move using the character's stat named stat. This move can be done using the following stats: edge, shadow, and wits. Provide an optional [bonus].

In case this is the first move of a new expedition, isscrolls will ask for a rank and save it for the character.

[bonus]
Roll an Undertake a Journey move. Provide an optional [bonus].

In case this is the first move of a new journey, isscrolls will ask for a rank and save it for the character.

[bonus]
Roll a move. In case of a miss , the character can choose to abort the expedition or continue with it. An additional [bonus] can be provided.
[bonus]
Roll a Reach Your Destination move. In case of a miss , the character can choose to abort the journey or continue with it. An additional [bonus] can be provided.

The following moves are made as the character interacts with others in the wild, fight duels, form bonds, supports their allies, and determines the ultimate fate.

stat [bonus]
Roll a move using the character's stat named stat. This move can be done using the following stats: heart, iron, and shadow. An additional [bonus] can be provided.
[bonus]
Roll a move. Provide an optional [bonus].
[bonus]
Roll a move. Provide an optional [bonus].
[bonus]
Roll a Make a Connection move. An additional [bonus] can be provided. Note that isscrolls does not ask you for a rank and does not track connections, this is up to the player.
[bonus]
Roll a move. An additional [bonus] can be provided.
[bonus]
Roll a Test Your Bond move. An additional [bonus] can be provided.
[bonus]
Roll a Test Your Relationship move. An additional [bonus] can be provided.
Roll a move.

When there are no other options, when the sword flips free of its sheath, when the arrow is nocked, when the shield is brought to bear, these moves can be made.

stat [bonus]
Roll an Enter the Fray move using the character's stat named stat. This move can be done using the following stats: heart, wits, and shadow.

In case this is the first move in a fight, isscrolls will ask for a rank and save it for the fight. Progress per harm will be tracked automatically according to the rank. For lower ranks (Troublesome - Formidable), progress will be shown as absolute numbers, e.g. 2/10. For higher ranks (Extreme and Epic) progress will be shown as decimal numbers and 0.25 represents one tick, e.g. 0.75/10 means that the character already made 3 ticks progress. An additional [bonus] can be provided.

stat [bonus]
Roll an move using the character's stat named stat. This move can be done using all stats. An additional [bonus] can be provided.
stat [bonus]
Roll an move using the character's stat named stat. This move can be done using all stats. An additional [bonus] can be provided.
[bonus]
Roll an move. An additional [bonus] can be provided. isscrolls checks automatically that your last move was a strong hit.
stat [bonus]
Roll a move using the character's stat named stat. This move can be done using the following stats: iron, and edge. An additional [bonus] can be provided.
stat [bonus]
Roll a move using the character's stat named stat. This move can be done using the following stats: iron, and edge. An additional [bonus] can be provided.
stat [bonus]
Roll a move using the character's stat named stat. This move can be done using the following stats: edge, heart, iron, shadow, and wits. An additional [bonus] can be provided.
Give the character initiative/let them take control. This can be useful when a player rolls a weak hit on Enter the Fray.

The commands represent important moves characters make during their quest.

Roll a move. The active vow will be set as fulfilled so that the player cannot activate it again. Your character receives experience points equal to the rank of the vow.
Roll a move. The active vow will be forsaken and removed from the list of vows. Your character will endure stress equal to the rank of the quest.
Roll a Reach a Milestone vow move. The progress of the active vow is advanced equal to the rank.
[bonus]
Roll a move. You will be asked for a title - which is like a short description of the vow - and a longer description. The prompt changes and shows the title of the active vow and the current progress. Provide an optional [bonus].

These moves are made as a result of a perilous event or bad outcome on other moves. They represent what happens to the character, and how they hold up against the trauma.

[value]
Roll an Endure Harm move. In case the character is in a fight, the amount of harm to suffer is automatically derived from the foe's rank. If the character is not in a fight, the amount of harm to suffer can be provided with the optional argument [value]. Since there are multiple options on what can happen on a “miss”, the decision is up to the player and not implemented in isscrolls.
[bonus]
Roll a Face Death move. In case the character dies, it is marked as such and “Deceased” is printed in the character's statistics. An additional [bonus] can be provided.
[bonus]
Roll a Face Desolation move. An additional [bonus] can be provided.
value
Roll an Endure Stress move. Provide a value that will be removed from your spirit. Since there are multiple reasons why the character can suffer stress, the amount of to suffer has to be provided and is not implemented within isscrolls.
value
Roll an move. Provide a value that will be removed from your supply.

These moves are part of the Ironsworn Delve supplement. They will help you delve into sites and hopefully locate your objective.

Roll a move. This is a progress move where the result is compared against the failure track. It can only be used if the character has more than 6 boxes marked in the failure track. The latter is automatically tracked by isscrolls and reset after this move. Although this is a character move, it is part of the Delve supplement.
Roll a move. This is the first move towards a delve into a site. isscrolls will ask for the site's rank.
stat [bonus]
Roll a Delve the Depths move using the character's stat named stat. This move can be done using edge, shadow, and wits. An additional [bonus] can be provided.
[bonus]
Roll a move. An additional [bonus] can be provided.
Roll a move.
stats [bonus]
Roll an This move can be done using edge, heart, iron, shadow, and wits. An additional [bonus] can be provided.

The following commands provide results from the various oracle tables in both the Ironsworn and Ironsworn Delve Rulebook.

Generate a random NPC with a role, a goal and their disposition.
Show a random action.
Show a random combat action.
Show a random coastal waters location.
Show a random elf name.
Show a random opportunity.
Show a random giant name.
Show a random Ironlander name.
Show a random location.
Show a random description for a location.
Roll random on the Sundered Isles moons, Wraith and Cinder.
Show a random mystic backslash.
Show a random “Pay the price” result.
Show a random plot twist.
Show a random rank.
Show a random Ironlands region.
Show a random danger region.
Show a random settlement trouble.
Show a random theme.
Show a random Varou name.

isscrolls makes use of the following environment variables.

If the XDG_CONFIG_HOME variable is not set, isscrolls stores its history and other data in the .config/isscrolls subdirectory in the user's home directory.
In case this variable is set, isscrolls stores its history and other data in the isscrolls subdirectory below the path set by this environment variable.

/usr/local/share/isscrolls
Contains shared files such as the JSON files for the oracle tables.

isscrolls normally exists with 0 or with 1 if an error occurred.

readline(3)

Shawn Tomkin, Ironsworn. A tabletop RPG of perilous Quests, https://www.ironswornrpg.com/, 2018.

Shawn Tomkin, Ironsworn Delve. Perilous Expeditions for the Ironsworn RPG, https://www.ironswornrpg.com/, 2020.

Shawn Tomkin, Ironsworn Starforged, https://www.ironswornrpg.com/, 2022.

isscrolls was written by Matthias Schmidt <xhr@giessen.ccc.de>.

February 18, 2026 ISSCROLLS(1)