Skill: Andamio CLI

Description

Manages Andamio platform content using the andamio CLI tool. Handles authentication, course queries, module import/export, and the full round-trip workflow from compiled content to live platform.

CLI location: /usr/local/bin/andamio Config: ~/.andamio/config.json

Prerequisites

Before running any commands, verify:

andamio --version    # CLI installed
andamio user status  # Authentication status

If not authenticated:

andamio user login   # Opens browser for wallet signing

If JWT is expired:

andamio user logout && andamio user login

Command Reference

Authentication

Course Queries

Module Export

andamio course export <course-id> <module-code> [flags]

Flags:

• --output-dir <dir> — Custom output path (default: ./compiled/<course-slug>/<module-code>/)
• --force — Overwrite existing directory

Output: Creates compiled directory with outline.md, lesson-N.md, introduction.md, assignment.md, and assets/ with .image-manifest.json.

Module Import (Update Existing)

andamio course import <path> --course-id <id> [flags]

Flags:

• --course-id <id> (required) — Target course ID
• --dry-run — Show API payload without sending

Requires: andamio user login (JWT auth)

Important: Import only updates existing modules and SLTs. The module must already exist in the course, and SLTs must be created before lessons can be imported. See "Creating New Modules" and "SLT Creation Gotcha" below.

What import does:

1. Parses outline.md for title, code, SLTs
2. Uploads new images in assets/ to CDN (preserves manifest entries)
3. Extracts # H1 from each lesson file as the lesson title
4. Converts remaining markdown to Tiptap JSON content
5. Merges with existing module state
6. Sends update to API

Critical file format rules:

• outline.md: No # H1 heading — title comes from YAML title: field. Start with ## SLTs after frontmatter.
• lesson-N.md: Must have # H1 title — this becomes the lesson title in the app. Content follows below.
• introduction.md: # H1 becomes intro title, rest is content.
• assignment.md: # H1 becomes assignment title, rest is content.

SLT locking rules:

• DRAFT modules: Can create/update/delete SLTs and lessons
• APPROVED/ON_CHAIN modules: SLTs are locked — can only update lesson content

Creating New Modules (API Direct)

The CLI has no create command yet. Use the API directly:

# Step 1: Create the empty module shell
andamio_url=$(python3 -c "import json; print(json.load(open('$HOME/.andamio/config.json'))['base_url'])")
jwt=$(python3 -c "import json; print(json.load(open('$HOME/.andamio/config.json'))['user_jwt'])")
api_key=$(python3 -c "import json; print(json.load(open('$HOME/.andamio/config.json'))['api_key'])")

curl -s -X POST "${andamio_url}/api/v2/course/teacher/course-module/create" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${jwt}" \
  -H "x-api-key: ${api_key}" \
  -d '{
    "course_id": "COURSE_ID_HERE",
    "course_module_code": "101",
    "title": "Module Title",
    "sort_order": 1
  }' | python3 -m json.tool

# Step 2: Import content into the newly created module
andamio course import ./compiled/course-slug/101 --course-id <course-id>

Parameters for create:

Other Commands

Workflows

Import a Single Compiled Module

# 1. Verify auth
andamio user status

# 2. Dry run first
andamio course import ./compiled/my-course/101 --course-id <id> --dry-run

# 3. Import for real
andamio course import ./compiled/my-course/101 --course-id <id>

# 4. Verify
andamio course slts <id> 101

Import All Modules in a Course

COURSE_ID="<course-id>"
COURSE_DIR="./compiled/course-slug"

for module_dir in "$COURSE_DIR"/*/; do
  echo "=== Importing $(basename $module_dir) ==="
  andamio course import "$module_dir" --course-id "$COURSE_ID"
done

Create + Import New Modules (Full Flow)

When modules don't exist on the platform yet, three steps are required:

1. Create module shell via API (no CLI command yet)
2. Create SLTs via API with slt_index omitted (triggers create instead of update)
3. Import content via CLI (lessons, assignment, introduction, images)

SLT Creation Gotcha

The CLI sends SLTs with slt_index set, which the API interprets as "update existing." For new modules with no SLTs, you must first create them via a direct API call with slt_index omitted:

# This CREATES SLTs (slt_index omitted)
curl -s -X POST "${andamio_url}/api/v2/course/teacher/course-module/update" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${jwt}" \
  -H "x-api-key: ${api_key}" \
  -d '{
    "course_id": "COURSE_ID",
    "course_module_code": "101",
    "slts": [
      {"slt_text": "First SLT text"},
      {"slt_text": "Second SLT text"}
    ]
  }'
# Response: "slts_created": 2

# After SLTs exist, CLI import works normally:
andamio course import ./compiled/course/101 --course-id COURSE_ID
# Response: "lessons_created": 2

Full Script

COURSE_ID="<course-id>"
COURSE_DIR="./compiled/course-slug"

andamio_url=$(python3 -c "import json; print(json.load(open('$HOME/.andamio/config.json'))['base_url'])")
jwt=$(python3 -c "import json; print(json.load(open('$HOME/.andamio/config.json'))['user_jwt'])")
api_key=$(python3 -c "import json; print(json.load(open('$HOME/.andamio/config.json'))['api_key'])")

sort_order=1
for module_dir in "$COURSE_DIR"/*/; do
  code=$(basename "$module_dir")
  title=$(grep '^title:' "$module_dir/outline.md" | sed 's/title: *"\{0,1\}\(.*\)"\{0,1\}/\1/' | sed 's/"$//')

  echo "=== Module $code: $title ==="

  # Step 1: Create module shell
  curl -s -X POST "${andamio_url}/api/v2/course/teacher/course-module/create" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ${jwt}" \
    -H "x-api-key: ${api_key}" \
    -d "{
      \"course_id\": \"${COURSE_ID}\",
      \"course_module_code\": \"${code}\",
      \"title\": \"${title}\",
      \"sort_order\": ${sort_order}
    }"

  # Step 2: Create SLTs (omit slt_index to trigger creation)
  slts=$(grep -E '^\d+\.' "$module_dir/outline.md" | sed 's/^[0-9]*\. *//' | python3 -c "
import sys, json
slts = [{'slt_text': line.strip()} for line in sys.stdin if line.strip()]
print(json.dumps(slts))
")
  curl -s -X POST "${andamio_url}/api/v2/course/teacher/course-module/update" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ${jwt}" \
    -H "x-api-key: ${api_key}" \
    -d "{
      \"course_id\": \"${COURSE_ID}\",
      \"course_module_code\": \"${code}\",
      \"slts\": ${slts}
    }" | python3 -c "import json,sys; d=json.load(sys.stdin); print(f'  SLTs created: {d.get(\"changes\",{}).get(\"slts_created\",0)}')"

  # Step 3: Import content (lessons, assignment, images)
  andamio course import "$module_dir" --course-id "$COURSE_ID"

  sort_order=$((sort_order + 1))
  echo ""
done

Export → Edit → Re-import (Round Trip)

# Export
andamio course export <course-id> 101

# Edit locally
vim compiled/course-slug/101/lesson-1.md

# Re-import (manifest preserves existing image URLs)
andamio course import compiled/course-slug/101 --course-id <course-id>

Image Handling

• Supported: PNG, JPEG, GIF, WebP (max 5MB per image)
• Upload: New images in assets/ are automatically uploaded to CDN on import
• Manifest: .image-manifest.json maps filenames → CDN URLs
• Round-trip safe: Export downloads images + writes manifest; import re-uses manifest URLs

Common Errors

Global Flags

All commands support:

• -o, --output <format> — Output format: text (default), json, csv, markdown

JSON output is useful for scripting:

andamio course modules <id> -o json | jq '.data[].course_module_code'

Environment

• Preprod: andamio config set-url https://preprod.api.andamio.io
• Mainnet: andamio config set-url https://mainnet.api.andamio.io
• Custom: Set ANDAMIO_ALLOW_ANY_URL=1 then andamio config set-url <url>