CLI Reference

Complete reference for Teachfloor CLI commands and options.

Installation

npm install -g @teachfloor/teachfloor-cli

Command Reference

Quick Reference Table

Global Commands

teachfloor version

Display CLI version and check for updates.

teachfloor version

Output:

teachfloor version 1.2.0
A newer version of the Teachfloor CLI is available: 1.3.0

teachfloor login

Authenticate with your Teachfloor account.

teachfloor login

Prompts:

• Email address
• Password
• Organization (if you have multiple)

What it does:

1. Authenticates with your Teachfloor account
2. Stores credentials securely
3. Saves selected organization

Example:

$ teachfloor login
✔ Enter your email: john@example.com
✔ Enter your password: ••••••••
✔ Select an organization: My Organization
✓ Login successful!

teachfloor logout

Log out from your Teachfloor account.

teachfloor logout

What it does:

1. Removes stored credentials
2. Clears organization selection

teachfloor whoami

Display current authenticated user and organization.

teachfloor whoami

Output:

User: john@example.com
Organization: my-organization

App Management

teachfloor apps create <app-name>

Create a new Teachfloor app.

teachfloor apps create my-awesome-app

Arguments:

• app-name: Name of the folder to create

Prompts:

• App ID: Unique identifier (auto-generated)
• Display Name: User-facing name
• Description: Short description
• Version: Semantic version (default: 1.0.0)

What it does:

1. Creates app on the platform
2. Generates project structure with all necessary files
3. Installs dependencies

Generated Structure:

my-awesome-app/
├── src/
│   ├── index.js
│   └── views/
│       └── App.jsx
├── public/
│   └── index.html
├── teachfloor-app.json
├── package.json
├── webpack.config.js
└── tsconfig.json

Example:

$ teachfloor apps create notes-app
✔ App ID: notes-1234567890
✔ Display Name: Notes App
✔ Description: Take notes while learning
✔ Version: 1.0.0
✓ Creating app...
✓ Setting up app structure...
✓ Installing npm dependencies...
✓ App "Notes App" created successfully in "notes-app".

teachfloor apps start

Start development server for your app.

teachfloor apps start

Options:

• -m, --manifest <path>: Use custom manifest file

What it does:

1. Validates your app manifest
2. Uploads manifest to platform
3. Opens browser to install the app
4. Starts development server with auto-reload

Requirements:

• Must be run inside an app folder
• Must be logged in
• Version must not be approved/published

Example:

$ cd my-app
$ teachfloor apps start
✓ Manifest file updated
Install URL: https://app.teachfloor.com/myorg/courses?app=abc123@1.0.0
Starting development server...
webpack 5.x.x compiled successfully

With custom manifest:

teachfloor apps start --manifest teachfloor-app.dev.json

teachfloor apps upload

Build and upload your app to the platform.

teachfloor apps upload

What it does:

1. Builds your app for production
2. Uploads bundled files to the platform
3. Creates a new version

Requirements:

• Must be run inside an app folder
• Must be logged in
• Version must not be already published

Example:

$ teachfloor apps upload
✓ Building the production bundle...
✓ Uploading files...
✓ App uploaded successfully.

View Management

teachfloor apps add view

Add a new view to your app.

teachfloor apps add view

Prompts:

1. Select viewport: Choose from available viewports
2. Component name: React component name (PascalCase)
3. Generate example: Include example code

What it does:

1. Shows available viewports for your app
2. Creates component file in src/views/
3. Updates your app manifest

Example:

$ teachfloor apps add view
✔ Select the viewport for your view: teachfloor.dashboard.course.list
✔ Enter the name of your component: CourseListView
✔ Generate a "Getting Started" example view? Yes
✓ Component view created at src/views/CourseListView.jsx
✓ Manifest file updated
✓ View "CourseListView" added successfully under "teachfloor.dashboard.course.list".

Generated Component:

import React from 'react'
import { Container, Text } from '@teachfloor/extension-kit'

const CourseListView = () => {
  return (
    <Container>
      <Text>CourseListView</Text>
    </Container>
  )
}

export default CourseListView

teachfloor apps remove view

Remove a view from your app.

teachfloor apps remove view

Prompts:

• Select viewport: Choose viewport to remove

What it does:

1. Removes view from your app manifest
2. Note: Component file remains in src/views/ (delete manually if needed)

Example:

$ teachfloor apps remove view
✔ Select the viewport to remove: teachfloor.dashboard.course.list
✓ View removed successfully.

teachfloor apps add settings

Add a settings view to your app.

teachfloor apps add settings

Prompts:

• Component name: Settings component name
• Generate example: Include example code

What it does:

1. Creates settings component in src/views/
2. Adds settings viewport to your manifest

Example:

$ teachfloor apps add settings
✔ Enter the name of your component: AppSettings
✔ Generate a "Getting Started" example view? Yes
✓ Settings view created at src/views/AppSettings.jsx
✓ Manifest file updated

Permission Management

teachfloor apps grant permission

Add a permission to your app.

teachfloor apps grant permission

Prompts:

1. Select permission: Choose from available permissions
2. Purpose: User-facing explanation

Available Permissions:

• user_read: Read user profile
• user_events_read: Read user activity
• course_read: Read course data
• module_read: Read module content
• element_read: Read learning elements

Example:

$ teachfloor apps grant permission
✔ Select permission: course_read
✔ Enter purpose: Display course information in notes
✓ Permission added to manifest.

Updates Manifest:

{
  "permissions": [
    {
      "permission": "course_read",
      "purpose": "Display course information in notes"
    }
  ]
}

teachfloor apps revoke permission

Remove a permission from your app.

teachfloor apps revoke permission

Prompts:

• Select permission: Choose permission to remove

Example:

$ teachfloor apps revoke permission
✔ Select permission to revoke: course_read
✓ Permission removed from manifest.

Distribution

teachfloor apps set distribution

Set app distribution type (public or private).

teachfloor apps set distribution

Prompts:

• Distribution type: public or private

Distribution Types:

• private: Only your organization (default)
• public: Listed in marketplace (requires review)

Example:

$ teachfloor apps set distribution
✔ Select distribution type: public
✓ Distribution type updated to public.

Updates Manifest:

{
  "distribution_type": "public"
}

Important for Marketplace Submission: You must set distribution to public before submitting your app for marketplace review. Apps with distribution_type: "private" cannot be submitted to the public marketplace.

Workflow for Public Apps:

# 1. Set distribution to public
teachfloor apps set distribution
# Select: public

# 2. Upload your app
teachfloor apps upload

# 3. Submit via dashboard
# Navigate to Settings → Apps → Your App → Submit for Review

Command Requirements

Authentication Required

These commands require authentication:

• teachfloor apps create
• teachfloor apps start
• teachfloor apps upload

Check authentication:

teachfloor whoami

Re-authenticate:

teachfloor logout
teachfloor login

App Folder Required

These commands must be run inside an app folder:

• teachfloor apps start
• teachfloor apps upload
• teachfloor apps add view
• teachfloor apps remove view
• teachfloor apps add settings
• teachfloor apps grant permission
• teachfloor apps revoke permission
• teachfloor apps set distribution

Check if in app folder:

ls teachfloor-app.json

Common Workflows

Create and Test App

# 1. Install CLI
npm install -g @teachfloor/teachfloor-cli

# 2. Login
teachfloor login

# 3. Create app
teachfloor apps create my-app
cd my-app

# 4. Add a view
teachfloor apps add view

# 5. Start dev server
teachfloor apps start

# 6. Make changes and test
# (dev server auto-reloads)

# 7. Upload when ready
teachfloor apps upload

Update Existing App

# 1. Navigate to app folder
cd my-app

# 2. Make code changes
# edit src/views/MyView.jsx

# 3. Update version in manifest
# Edit teachfloor-app.json: "version": "1.1.0"

# 4. Test locally
teachfloor apps start

# 5. Upload new version
teachfloor apps upload

Add View to Existing App

cd my-app

# Add view
teachfloor apps add view
# Select viewport and enter component name

# Implement component
# edit src/views/NewView.jsx

# Test
teachfloor apps start

Troubleshooting

"Not logged in" error

Solution:

teachfloor login

"Not in app folder" error

Check for manifest:

ls teachfloor-app.json

Create new app if needed:

teachfloor apps create my-app
cd my-app

"Version already approved" error

Solution: Increment version in teachfloor-app.json:

{
  "version": "1.0.1"
}

Build errors

Clear cache:

rm -rf node_modules
npm install
npm run build

Getting Help

Built-in Help

teachfloor --help
teachfloor apps --help
teachfloor apps create --help

Version Info

teachfloor version

Support Channels

• Email: support@teachfloor.com
• Documentation: docs.teachfloor.com

Next Steps

Learn about best practices:

→ Continue to Best Practices

Additional Resources

• Quickstart Guide
• App Manifest
• Deployment