Copy page

References

CLI Reference

Complete reference for Teachfloor CLI commands and options.

Installation

Code
npm install -g @teachfloor/teachfloor-cli

Command Reference

Quick Reference Table

Command	Description	Requires Auth	Requires App Folder
Global
teachfloor version	Display CLI version	No	No
teachfloor login	Authenticate with Teachfloor	No	No
teachfloor logout	Log out from account	No	No
teachfloor whoami	Show current user and org	Yes	No
App Management
teachfloor apps create <name>	Create new app	Yes	No
teachfloor apps start	Start dev server	Yes	Yes
teachfloor apps upload	Build and upload app	Yes	Yes
View Management
teachfloor apps add view	Add view to app	Yes	Yes
teachfloor apps remove view	Remove view from app	Yes	Yes
teachfloor apps add settings	Add settings view	Yes	Yes
Permission Management
teachfloor apps grant permission	Add permission	Yes	Yes
teachfloor apps revoke permission	Remove permission	Yes	Yes
Distribution
teachfloor apps set distribution	Set public/private	Yes	Yes

Global Commands

teachfloor version

Display CLI version and check for updates.

Code
teachfloor version

Output:

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

---

teachfloor login

Authenticate with your Teachfloor account.

Code
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:

Code
$ 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.

Code
teachfloor logout

What it does:

1. Removes stored credentials
2. Clears organization selection

---

teachfloor whoami

Display current authenticated user and organization.

Code
teachfloor whoami

Output:

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

---

App Management

teachfloor apps create <app-name>

Create a new Teachfloor app.

Code
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:

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

Example:

Code
$ 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.

Code
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:

Code
$ 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:

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

---

teachfloor apps upload

Build and upload your app to the platform.

Code
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:

Code
$ 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.

Code
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:

Code
$ 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:

Code
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.

Code
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:

Code
$ 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.

Code
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:

Code
$ 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.

Code
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:

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

Updates Manifest:

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

---

teachfloor apps revoke permission

Remove a permission from your app.

Code
teachfloor apps revoke permission

Prompts:

• Select permission: Choose permission to remove

Example:

Code
$ 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).

Code
teachfloor apps set distribution

Prompts:

• Distribution type: public or private

Distribution Types:

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

Example:

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

Updates Manifest:

Code
{
  "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:

Code
# 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:

Code
teachfloor whoami

Re-authenticate:

Code
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:

Code
ls teachfloor-app.json

---

Common Workflows

Create and Test App

Code
# 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

Code
# 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

Code
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:

Code
teachfloor login

"Not in app folder" error

Check for manifest:

Code
ls teachfloor-app.json

Create new app if needed:

Code
teachfloor apps create my-app
cd my-app

"Version already approved" error

Solution: Increment version in teachfloor-app.json:

Code
{
  "version": "1.0.1"
}

Build errors

Clear cache:

Code
rm -rf node_modules
npm install
npm run build

---

Getting Help

Built-in Help

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

Version Info

Code
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