The Instruqt Command-Line Interface (CLI) is a text-based interface that accepts commands to create and maintain tracks. Instruqt CLI commands let you do things like:
Push your local changes to the Instruqt platform to update the track.
Start an automated test of the track.
Learn how to install the CLI in our Setting up guide.
Instruqt CLI commands
Instruqt CLI commands always start with the instruqt directive, followed by a command with an optional subcommand and optional flags.
For example, challenge is a command which has a create subcommand and a --title flag:
instruqt challenge create --title "Create a Kubernetes cluster"
But version is a command on its own:
instruqt version
Available commands
To get started working with your content you can specify your team (org name) with the following command:
instruqt config set team your-team-name
To explore the available commands, open a terminal on your machine and enter the following command:
instruqt --help
↳ Instruqt CLI shows the available commands:
active-users
List all users playing an invite.
auth
Authentication commands.
challenge
Create and manage challenges.
completion
Generate shell auto completion scripts.
config
View and edit Instruqt CLI configuration.
developer
Manage the developers of a track.
help
Help about any command.
note
Create and manage notes.
track
Create and manage tracks.
update
Update the CLI.
version
Show the version of the CLI.
Drill down commands
You can drill down any command with the --help flag—for example the track command:
instruqt track --help
↳ After which Instruqt CLI shows the subcommands for track command:
Available Commands:
checksum Get the track checksum
create Create a new track
delete Delete a remote track
deploy Deploy a remote track
logs Get logs for the track
open Open the track URL in a browser
pull Pull the track from the remote server
push Push the local track to the remote server
test Test the track with its lifecycle scripts
upgrade Upgrade track version.
validate Validate the local track
And you can even further drill down by adding a subcommand:
instruqt track create --help
↳ After which Instruqt CLI shows examples and the flags for the create subcommand:
Examples:
If you omit the track slug (TRACK), one is generated based on the title:
$: instruqt track create --title "My first track"
To copy an existing track:
$: instruqt track create --from instruqt/docker-basics --title "My new track"
Flags:
--from string The remote track to copy: '<organization-slug>/<track-slug>'
-h, --help help for create
--title string The title of the track
Telemetry and crash reports
The Instruqt CLI collects basic usage statistics that help us develop the product. No personal information is collected. You can disable telemetry with the following command:
instruqt config set telemetry false
Our CLI submits crash reports automatically to Instruqt via Sentry, which helps us fix issues you may encounter faster. You can disable crash-reports with the following command:
instruqt config set report-crashes false
Commonly used commands
The following commonly used commands are further specified for your reference:
instruqt track create
Synopsis
instruqt create track [--from | --title]
Description
The create command scaffolds a local directory with track configuration files.
Flags
--from
The remote track to copy: '<organization-slug>/<track-slug>'
--title
The title of the track
Examples
To create a new track as a copy of an existing track:
instruqt track create --from instruqt/docker-basics --title "My new track"
instruqt challenge create
Synopsis
instruqt create challenge [--title]
Description
The create command creates a new challenge locally and generates the template files for you.
Flags
--title
The title of the challenge
Example
To create a new challenge:
instruqt challenge create --title "Create a Kubernetes cluster"
instruqt track push
Synopsis
instruqt track push [--force]
Description
Push the local track to the Instruqt platform.
Note: The org/team for the destination is configured in the track.yml file under "owner". The configured team via the CLI doesn't impact the destination for the pushed track.
Flags
--force
Force push the track. Overwrites remote changes.
Example
To push a track to the Instruqt platform overwriting remote changes:
instruqt track push --force
instruqt track test
Synopsis
[INSTRUQT_TOKEN="..."] instruqt track test [--keep-running |
--skip-fail-check]
Description
Test the track with all lifecycle scripts (setup / check / solve / cleanup).
Preceding argument
INSTRUQT_TOKEN
Enter your API token for your team here to set the INSTRUQT_TOKEN environment variable when running the test command from a CI/CD system.
Flags
--keep-running
Keep the environment running when the test finishes or fails.
--skip-fail-check
Don't fail the test if running the first challenge check doesn't fail.
Examples
To run a test from your machine that keeps the environment running when the test finishes:
instruqt track test --keep-running
To run a test from a CI/CD system:
INSTRUQT_TOKEN = "YOUR_API_TOKEN" instruqt track test
