Commands

Overview of Instruqt CLI commands.

Overview

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:

• Create a new track from scratch.

• Pull the configuration files of an existing track.

• 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

instruqt track logs

Synopsis

instruqt track logs [--participant-id | --since | --severity]

Description

The logs command tails logs of the track.

Flags

--participant-id

The participant ID. When set, this will take precedence over track ID or slug.

--since

The start datetime from which to return logs, either in relative duration.

--severity

The severity of the log entries, e.g DEBUG, INFO, ERROR. Defaults to INFO.

Example

To log a track, starting 30 minutes ago:

instruqt track logs --since 30m