Creating Labs

CLI Workflow

Validate, deploy, and test labs using the tekanaid CLI. Always validate before pushing, then publish through the platform after deploying.

CLI Commands

tekanaid validate

Validate lab.yml and config.yml in the current directory.

tekanaid push

Deploy the lab to the platform.

tekanaid validate-batch <dir>

Validate all labs in a parent directory.

tekanaid push-batch <dir>

Deploy all labs in a parent directory.

tekanaid lab-start <slug>

Start a lab session for manual testing.

tekanaid lab-status <slug>

Get status of a running lab session.

tekanaid lab-stop <slug>

Stop and clean up a lab session.

tekanaid test <slug>

Run automated lab tests (assignments or skips mode).

tekanaid list-labs

List all available labs in your account.

tekanaid migrate <path> [output]

Convert an Instruqt lab at the given path into TeKanAid format. Output defaults to the current directory.

tekanaid migrate-batch <dir> [output]

Convert all Instruqt labs under a directory.

Deploy Workflow

Follow these steps when creating or updating a lab:

1Create your lab directory with lab.yml, config.yml, and numbered task directories.
2Validate locally: tekanaid validate
3Set TEKANAID_ENV=production and TEKANAID_TARGET=povdemo, then run tekanaid push.
4Log in to POV Demo and publish the lab to make it available to learners.

# Validate
tekanaid validate

# Deploy
export TEKANAID_ENV=production
export TEKANAID_TARGET=povdemo
tekanaid push

Testing Labs

Use tekanaid test to run automated tests, or start a live session for manual testing.

Automated Testing

Two test modes are available:

--mode assignments

Extracts commands from Markdown and runs setup/check scripts. Validates instruction clarity.

--mode skips

Runs setup → solve → check for each task. Validates that solve scripts produce passing check results.

# Test in assignments mode (default)
tekanaid test my-lab-slug --mode assignments --verbose

# Test in skips mode (CI/CD validation)
tekanaid test my-lab-slug --mode skips --timeout 30m

# Output JSON for CI
tekanaid test my-lab-slug --mode skips --output-format json > results.json

# Keep session alive after test for debugging
tekanaid test my-lab-slug --mode skips --no-cleanup

Manual Session Testing

Start a live session to interact with the lab VMs directly:

# Start a session (waits until VMs are ready and shows IP addresses)
tekanaid lab-start my-lab-slug

# Check session status
tekanaid lab-status my-lab-slug

# Stop the session when done
tekanaid lab-stop my-lab-slug

Batch Operations

Use batch commands when managing multiple labs in a shared parent directory. Each subdirectory must contain a lab.yml and config.yml:

# Validate all labs under ./labs/
tekanaid validate-batch ./labs

# Deploy all
export TEKANAID_ENV=production
export TEKANAID_TARGET=povdemo
tekanaid push-batch ./labs

Troubleshooting

Common errors and fixes:

Error	Cause	Fix
`missing required field: slug`	lab.yml is missing the slug field.	Add slug: "your-slug" to lab.yml.
`invalid vm name`	Script filename references a VM name not in config.yml.	Match script names to the name fields in config.yml.
`check script exited non-zero`	A check script failed during tekanaid test.	Run tekanaid lab-start and debug the check script manually.
`not authenticated`	You're not logged in or your session expired.	Run tekanaid login.
`lab not found`	The slug doesn't match any published lab.	Run tekanaid list-labs to see available slugs.