Four commands are enough to pick a lab in a catalogue: dsoxlab use sets the
scope, list-labs browses it, show details a lab and next suggests the
following one. This lesson is for anyone who has installed a catalogue and
wonders where to begin. It shows how to narrow the list to a section and a
level, filter by type or by block, read a lab's sheet before committing to it,
and let dsoxlab next decide what comes after, based on your results. The labs
are then played with the loop seen in the lesson
Playing your first dsoxlab lab.
What you will learn
- Set an active context with
dsoxlab use, then clear it with--reset. - Browse a catalogue with
dsoxlab list-labsand its filters. - Interpret the columns of the table, including the best score.
- Consult a lab's sheet with
dsoxlab showbefore playing it. - Get the next lab with
dsoxlab next, and understand its verdict.
Prerequisites
You need dsoxlab 0.6.0 or newer, and an active catalogue: the demonstration
lab of the lesson
Playing your first dsoxlab lab, or a catalogue
installed as the lesson
Installing and managing your catalogues describes.
The test is simple: dsoxlab list-labs prints at least one line.
How do you browse the list of labs with list-labs?
dsoxlab list-labs prints one line per lab of the catalogue served, with its
section, its identifier, its title, its type, its level, its runtime, its
estimated duration and its best score. The section is a grouping of labs
defined by the catalogue, and the level a difficulty label carried by each lab.
The runtime says where the lab is played, shell in a directory on your
machine or vm on real machines. The type is lab, challenge, capstone or
validation; the capstone is a mock exam, and the validation defends a guide
of the site: it is not graded and next never suggests it.
dsoxlab list-labs Available labs┏━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━┳━━━━━━━┓┃ Section ┃ ID ┃ Title ┃ Level ┃ Duration ┃ Score ┃┡━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━╇━━━━━━━┩│ demo │ premiers-pas │ First steps with dsoxlab │ demo │ 5m │ · │└─────────┴──────────────┴──────────────────────────┴───────┴──────────┴───────┘ℹ 2 of 8 columns are hidden, for lack of width: dsoxlab list-labs --long showsthem all.The Score column shows · as long as no pass of check has been recorded for
that lab, then the best score obtained. Four options narrow the list:
--section, --level, --type and --bloc (a number from 1 to 8, which the
lab declares in its sheet), each with a short form (-s, -l, -t, -b). In a
narrow terminal, or when a column has the same value everywhere, the CLI hides
some columns and says so; the --long option forces all eight columns (section,
ID, title, type, level, runtime, duration, score), and --json returns a
document with the labs list and a count, useful for a script.
dsoxlab list-labs --type capstonedsoxlab list-labs --section drills --level l2These two commands, like the examples that follow, run on the Linux catalogue
(dsoxlab catalog add linux), which arranges its labs in the sections l1 to
l4, drills, capstones, lfcs and ebpf. The first filter keeps only the
mock exams, the second the labs of the drills section at level l2.
The success criterion is that the list contains only the labs requested. A
filter with no match gives the message "No labs found." instead of a table: check
the spelling of the section, which list-labs --long shows in its first column.
How do you set a context with dsoxlab use?
dsoxlab use <section>[/<level>] records an active context that the following
commands apply on their own. Without it, you would have to repeat --section
and --level on every call. The context is written to the
.dsoxlab-context.json file, at the root of the catalogue, and it survives
closing the terminal.
dsoxlab use drills/l2dsoxlab list-labs✔ Active context: drills/l2ℹ Commands list-labs and validate-structure now use this filter by default.ℹ Active context: drills/l2 — use dsoxlab use --reset to see all. Available labs┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━┳━━━━━━━┓┃ ID ┃ Title ┃ Level ┃ Duration ┃ Score ┃┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━╇━━━━━━━┩│ drill-users-groups │ Drill : utilisateurs, │ l2 │ 20m │ · ││ │ groupes et délégation en │ │ │ ││ │ conditions d'examen │ │ │ │├────────────────────┼──────────────────────────────┼───────┼──────────┼───────┤│ drill-storage │ Drill : partitions, LVM et │ l2 │ 25m │ · ││ │ swap en conditions d'examen │ │ │ │├────────────────────┼──────────────────────────────┼───────┼──────────┼───────┤│ drill-packages │ Drill : gestion des paquets │ l2 │ 20m │ · ││ │ en conditions d'examen │ │ │ │└────────────────────┴──────────────────────────────┴───────┴──────────┴───────┘ℹ 3 of 8 columns are hidden, for lack of width: dsoxlab list-labs --long showsthem all.The success criterion is the "Active context" line recalled at the top of every
list-labs, followed by a table narrowed to that section and that level. The
value is split at the first /: drills/l2 sets the section and the level. A
section given alone keeps the level already set: after dsoxlab use drills/l2,
the command dsoxlab use capstones answers "Active context: capstones", but the
l2 level is still applied silently. To change section, first run
dsoxlab use --reset, or give the whole section/level. If the catalogue
declares its sections in its meta.yml, an unknown section is refused with
the list of those that exist, and the command exits with code 1:
dsoxlab use linux answers 'Unknown section: "linux". The catalog would come
out empty.', because linux is the name of the catalogue, not that of a
section. The level, for its part, is not checked: a level the section does
not carry is accepted, then list-labs answers "No labs found." and next
exits with code 1.
To clear the context, type dsoxlab use --reset, or dsoxlab use with no
argument at all, which does the same thing. The CLI then answers that all the
labs are visible again. The context only carries the section and the level; the
language (--lang), the target (--target) and the provider (--provider) are
three separate settings that the same command can set, and which are outside
the subject of this lesson.
How do you read a lab's sheet with dsoxlab show?
dsoxlab show <identifier> prints a lab's sheet: enough to decide whether to
play it, without starting anything. It gives the section, the title, the level,
the runtime, the duration, the difficulty, the distributions supported, the skills
targeted, the associated guide of the site, the training path, the
certifications, the type, the block, and two items of state: the status and
the validation mode.
dsoxlab show premiers-pasThe success criterion is being able to answer three questions by reading the
sheet: where the lab is played (the runtime), how long it takes (the duration) and
which skill it works on (the skills field). The status is ready when the lab's
working directory exists and stopped otherwise (for a shell lab): it changes
when you launch run. The dsoxlab status command gives, for its part, the
progress of the active lab: not started, ready, in progress or validated. An
unknown identifier gives an error message and exit code 1: copy the identifier
from the ID column of list-labs.
How do you get the next lab with dsoxlab next?
dsoxlab next suggests the first lab with no result, in the teaching order the
catalogue declares. It takes the active context into account: with
drills/l2, it looks in that section and that level. With no active context, it
walks the whole catalogue and does not exit with an error. A lab counts as done
as soon as a result is recorded for it, even if that check failed: a 0/100 is
enough to remove it from the list.
dsoxlab next✔ Next recommended: premiers-pas — First steps with dsoxlabWhen all the labs in the scope have a result, the command answers "All labs
validated in this context!" and sends you to dsoxlab progress, which summarises
progress. With no active catalogue, or in a catalogue (or a context) that holds
no lab, it exits with code 1 with "This catalog holds no lab. Check how it was
installed: dsoxlab doctor"; with no active catalogue, that line is preceded by
"No active catalog. Try dsoxlab demo for a first lab, or dsoxlab catalog add
linux for a full course.". With --json, it returns the lab suggested in the
next key, an all_done boolean and the number of labs remaining.
Keep the loop in mind: next gives the identifier, show confirms the choice,
then dsoxlab start <identifier> or dsoxlab run <identifier> opens the
session, a gesture described in the lesson
The main dsoxlab commands. Replaying a lab that
already has a mark does not change the suggestion of next: only a lab with
no result counts.
Troubleshooting
Each row starts from the message or behaviour observed, gives the cause and the gesture that fixes it. The four commands of the lesson read the catalogue served, and most surprises come from a forgotten context.
| Symptom | Cause | Solution |
|---|---|---|
list-labs shows only some of the labs | A context is active and filters the list, the first line recalls it | dsoxlab use --reset |
| "No labs found." | The filter matches no lab, or the section is misspelled | Remove the options, reread the Section column, run again |
use refuses the section with the list of those that exist | The section is not declared in the catalogue's meta.yml | Pick one of the sections cited |
show exits with code 1 | The identifier does not exist in the catalogue served | Copy the identifier from the ID column of dsoxlab list-labs |
next suggests a lab you have already played | No result is recorded: it was played without check | dsoxlab check <identifier> records the result |
next answers "All labs validated" although the last check failed | A recorded result, even at 0/100, is enough to remove the lab | dsoxlab scores to reread the mark, then dsoxlab run <identifier> and check to raise it |
list-labs answers "No labs found." with an active context, and next exits with code 1 | The level set does not exist in the section, or it dates from a previous context: use <section> alone does not clear it | dsoxlab use --reset, then dsoxlab use <section>/<level> after rereading the Level column with list-labs --long |
next or list-labs do not find your catalogue | The catalogue served is not the one expected | See the resolution order in the lesson Installing and managing your catalogues |
Key points
dsoxlab use <section>/<level>sets a context written to.dsoxlab-context.json;--reset, orusewith no argument, clears it.dsoxlab list-labsprints section, ID, title, type, level, runtime, duration and best score, and is filtered by--section,--level,--type,--bloc.- The active context applies on its own to
list-labsand tonext: it is the first setting to check when a list looks incomplete. dsoxlab show <id>gives a lab's sheet, including its status, without starting anything.dsoxlab nextsuggests the first lab with no result, in the catalogue's order, and the active context limits its scope.- A lab counts as done once a result is recorded: it is
checkorsubmitthat produces it.
Knowledge check
Check that you have the essentials of this guide. The questions only cover what has just been explained here.
Knowledge check
Check what you have learned with this interactive quiz
How it works
- The timer starts when you click Start
- Multiple choice, true/false and short answer questions
- You can move between questions
- Detailed results are shown at the end
Starts the quiz and the timer
Review
(0/0)Score by domain
A domain groups several guides and gets several questions, so its score is more reliable than a per-topic score, which often rests on a single question.
Summary
Strengths
No topic passed at 80% on at least two questions yet.
Weak areas
No topic below the pass mark.
Recommended next
Hints before you try again?
Continue the course: The main dsoxlab commands, in the order you use them
A new full quiz with random questions
Work again only on the questions you missed