IDEALIT Passport
Menu

Passport search

Find a lesson or fix

Type at least two characters.

    Browse help by symptomBrowse all references
    How to start
    Public course previewThis is not your assigned passport. No identity, answers, or completion progress are stored here.How to start your passport
    Handbook / workbook

    workbook

    Start The IDEAL Lab IT Passport

    View this page on GitHubHow to start your Passport

    Use this page only to install the two prerequisites and launch the local browser Passport. Once the browser opens, follow its single current lesson. This page is also the text fallback when JavaScript is unavailable; it is not a second path through the course.

    Local means on the computer in front of you. Windows, macOS, and Linux are operating systems: the basic software that runs that computer.

    0. Before You Run A Command#

    A command is a line of text that tells a computer to do one task. You type or paste commands into a terminal, the text application used for commands. A shell is the part inside that application that reads the command. This guide uses PowerShell on Windows, zsh on macOS, and Bash on Linux. Open the application named below; it starts the correct shell automatically. You do not need to install a separate Bash or zsh application.

    • Windows: press the Windows key, type PowerShell, and open it. Windows Terminal is also suitable when its tab says PowerShell. A ready prompt normally begins with PS. Opening PowerShell starts the text window and shell together. Do not use Command Prompt, Git Bash, or WSL for a block labelled PowerShell.
    • macOS: press Command+Space, type Terminal, and press Return. The window starts zsh for you and normally shows a prompt ending with %. Do not look for a separate zsh app.
    • Linux: open the application named Terminal from the applications menu. Ubuntu starts Bash for you and normally shows a prompt ending with $. Do not look for a separate Bash app.

    The prompt is the text beside the blinking cursor when the shell is ready. The command is the instruction you type or paste after it. The output is the text printed after you press Enter. A path is the address of a file or folder, such as C:\Users\Ada or /home/ada.

    For example, in this short PowerShell session, the first and last PS C:\Users\Ada> are prompts already printed by PowerShell. Paste only git --version; the middle line is the output:

    PS C:\Users\Ada> git --version
git version 2.51.0
PS C:\Users\Ada>

    For every command in this guide:

    1. copy only the text inside the code block;
    2. click once after the terminal prompt and paste;
    3. press Enter once;
    4. wait until the output stops and the prompt returns;
    5. compare the output with the stated expected result.

    Do not type the example prompt, a heading, or the expected output. When a code block contains several lines, paste the complete block once. If it prints an error, stop at that step; do not add sudo or administrator rights unless the instructions explicitly require them.

    Before installing anything, run one harmless practice command for your computer. It only prints terminal-ready.

    Windows PowerShell:

    Write-Output "terminal-ready"

    macOS or Linux Terminal:

    printf 'terminal-ready\n'

    Expected: the next line is terminal-ready, followed by the prompt again. If that happens, you have opened the correct application and run one command.

    1. Install The Two Prerequisites#

    Four names appear in this setup:

    • Git is a program on your computer that records file changes and their history.
    • GitHub is a website that stores shared Git projects, called repositories, and their reviews.
    • GitHub CLI is the command-line program named gh used to sign in to GitHub and perform GitHub actions. CLI means command-line interface.
    • The Passport launcher is an extension, or add-on, for GitHub CLI that opens this guided course locally in your browser.

    You need only Git and GitHub CLI to start. You do not need Python, VS Code, Obsidian, SSH, or an AI tool yet. A later lesson introduces each required tool before asking you to install or use it.

    Use the terminal you opened above. Run one command at a time:

    git --version
gh --version

    Expected: each command prints a version. If both work, skip installation.

    Windows 10 Or 11 / PowerShell#

    winget is the package installer included with current Windows versions. Run only the missing installer:

    winget install --id Git.Git -e --source winget

    winget install --id GitHub.cli -e --source winget

    Expected: the installer reports success. Close the entire PowerShell window, open a new one, and repeat the two version checks. If winget is unavailable, use the official Git installer and official GitHub CLI installer.

    macOS / Terminal With zsh#

    Run git --version; macOS offers the Command Line Tools installer if needed. Homebrew is an optional macOS package installer. If it is already installed, install GitHub CLI with:

    brew install gh

    If Homebrew is absent, open the official GitHub CLI releases, expand Assets, download the file ending in macOS_universal.pkg, and open that package with Installer. Do not download Source code. If macOS blocks the official package, stop and use the help path rather than weakening Gatekeeper. Do not install Homebrew only for this onboarding.

    Linux / Local Terminal#

    First identify the distribution. This command changes nothing:

    cat /etc/os-release

    Read the line beginning with ID=. If this is an ETH-managed computer and you do not normally use sudo, stop and request Git and GitHub CLI from its IT support.

    sudo runs the following installation command with administrator rights and may ask for this computer's password without showing characters as you type. APT is the package installer used by Ubuntu and Debian.

    If the line is ID=ubuntu or ID=debian on your personal computer, run these blocks one at a time:

    (
set -eu
sudo apt update
sudo apt install --yes git wget
)

    (
set -eu
sudo mkdir -p -m 755 /etc/apt/keyrings
out=$(mktemp)
cleanup() { rm -f "$out"; }
trap cleanup EXIT HUP INT TERM
wget -nv -O"$out" https://cli.github.com/packages/githubcli-archive-keyring.gpg
sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg < "$out" > /dev/null
sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg
sudo mkdir -p -m 755 /etc/apt/sources.list.d
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
sudo apt update
sudo apt install --yes gh
)

    Expected: both packages install without an APT signature error. Close this terminal, open a new one, and repeat both version checks.

    For Fedora, RHEL, Arch, openSUSE, or another distribution, do not run the APT commands. Use the official Git instructions for your distribution and the GitHub-maintained CLI package instructions, selecting only the section that names your distribution and package manager. Do not substitute a third-party install script. The Passport is tested with GitHub's maintained Linux package or release binary, not the confined Snap package.

    If an installer is blocked or asks for administrator approval, stop. Keep the short non-secret message and use the safe help page. Do not change security policy, antivirus, SSH files, or system permissions.

    2. Start Once#

    If you do not have GitHub yet, create one free personal account at https://github.com/signup using an email address you will keep. Add and verify your ETH email later in the Git lesson's GitHub Education steps. Do not use a shared lab account.

    Check the active account before changing anything:

    gh auth status --active --hostname github.com

    Expected: the status command reports the account you intend to use. If it does, keep that login and skip to installing the extension. If no account is active, run the login command, finish the browser approval, then repeat the status check:

    gh auth login --hostname github.com --web --git-protocol https
gh auth status --active --hostname github.com

    If the correct account is already stored but another account is active, switch without removing it:

    gh auth switch --hostname github.com --user YOUR-GITHUB-USERNAME
gh auth status --active --hostname github.com

    Replace YOUR-GITHUB-USERNAME before running the command. Never continue under another person's account and do not log out a working account merely to switch.

    gh extension install soheylm-passport-sandbox/gh-passport --force --pin v0.12.1

    Expected: the launcher installs without an error.

    gh passport start

    Expected: a browser opens at an address beginning with http://127.0.0.1:. This means the page is served only from your own computer. Keep that terminal open because the launcher in it is running the page. Select your computer and the work you will actually do. Read the public-record notice before confirming; no public exercise copy or record is created before that confirmation.

    You may see soheylm-passport-sandbox in links. This is the GitHub group that hosts the course software for the current semester. Continue with your personal GitHub account and do not request membership in that group.

    3. Follow One Current Lesson#

    The progress page always gives one next action. A lesson follows this order:

    1. understand the outcome and concept;
    2. inspect one correct example and one common trap;
    3. perform the stated action on the named computer and in the named application;
    4. compare the observed result with the expected result;
    5. choose Check my work;
    6. correct the specific feedback until the lesson is ready;
    7. review the public-content confirmations and choose Submit lesson once;
    8. continue only after the trusted GitHub result appears.

    Do not create or edit submission files yourself. Follow only the current lesson; the launcher manages its public learning record in the background.

    4. Submit One Lesson#

    The lesson page creates a safe public submission record. If the lesson has a fictional practice file, it submits only the exact file named by that lesson. It never submits other files from your computer.

    Before Submit lesson, confirm that the generated answers and declared fictional practice files contain no credential, private path, ETH identifier, real log, research data, screenshot, or confidential detail. Your GitHub username and the exercise result are public.

    Expected: the page says Submitted to GitHub, waits for the automatic check, and then opens the progress page. Do not submit the same work again. If no result appears after 30 minutes, use the progress page's public non-secret help link once and return later.

    When the Git lesson begins, the Passport creates a separate practice folder and explains the required concepts and commands there. Until then, you do not need to understand or operate the record behind Submit lesson.

    5. Resume Later#

    Close the browser and stop the local server with Ctrl+C when finished. Later, open PowerShell or a terminal and run this from any folder:

    gh passport open

    Expected: the browser restores the last page saved on this computer and then synchronizes trusted completion from GitHub. Do not reinstall or clone again.

    6. If Blocked#

    Run from any folder:

    gh passport doctor

    Keep the exact short non-secret error. Do not repair SSH, permissions, remotes, branches, PowerShell execution policy, or antivirus settings by guessing. Use the progress-page help link or the troubleshooting index.

    7. Finish Line#

    Training is complete only when the trusted progress page says all assigned lessons are complete. A local checkbox, browser history, or AI answer is not a completion record. Real account access, data ownership, or authorization may still require the separately named operational owner; this does not make a routine training lesson wait for a person.