Command Reference¶

embsec init¶

Sets up your environment for the first time.

embsec init [options]

Options: - --check - Just check if system is ready (no download) - --force - Reinstall everything

What it does: 1. Checks Docker is installed 2. Downloads the container image (~850MB) 3. Sets up configuration files

When to use: Once, after installing embsec

Starts the development environment.

embsec up [path] [options]

Arguments: - path - Directory to mount (default: current directory)

Options: - --no-vscode - Start without opening VS Code - --port 8080 - Use different port (default: 8443)

What it does: 1. Starts the Docker container 2. Mounts your project directory 3. Connects USB devices (TM4C123G) 4. Opens VS Code in browser

Examples:

# Start in current directory
embsec up

# Start with specific project
embsec up ~/labs/project1

# Use different port
embsec up --port 8080

Stops the development environment.

embsec down [options]

Options: - --purge - Also remove downloaded images (frees space)

What it does: 1. Saves your work 2. Disconnects USB devices 3. Stops the container

Examples:

# Normal stop
embsec down

# Free up disk space
embsec down --purge

Shows if the environment is running.

embsec status [options]

Options: - --brief - One-line summary

What it shows: - Container running/stopped - VS Code URL - Connected USB devices - Resource usage

Example output:

Container:    ● Running (2h 14m)
VS Code:      http://localhost:8443
USB Devices:  TM4C123G LaunchPad connected
Resources:    CPU: 12% • RAM: 487 MB

Diagnoses and fixes common problems.

embsec doctor [options]

Options: - --usb-only - Just check USB connection - --fix - Try to fix problems automatically

What it checks: - Docker installation and permissions - USB device access - Port availability - Disk space

When to use: When something isn't working

Updates the tools to the latest version.

embsec update [options]

Options: - --check-only - Just check for updates

What it updates: - The embsec CLI tool - The Docker container image

Shows container output for debugging.

embsec logs [options]

Options: - --follow - Show logs in real-time - --tail 20 - Show last N lines

When to use: If VS Code won't start or USB isn't working

Manages configuration settings.

embsec config [subcommand]

Subcommands: - show - Display all settings - set <key> <value> - Change a setting - reset - Reset to defaults

Common settings: - vscode.port - Change VS Code port - usb.passthrough - Enable/disable USB

Examples:

# Show current config
embsec config show

# Change VS Code port
embsec config set vscode.port 8080

Every command has built-in help:

embsec --help
embsec up --help
embsec config --help

"Port already in use"

embsec config set vscode.port 8444
embsec up

"Permission denied"

# Linux only
sudo usermod -aG docker $USER
# Log out and back in

"USB device not found"

# Check USB connection
embsec doctor --usb-only

# Make sure device is connected before starting
embsec down
# Connect TM4C123G
embsec up