timeback 0.1.5 → 0.1.7

package/README.md

@@ -19,6 +19,40 @@ timeback --help
 
 ## Commands
 
+### `timeback resources`
+
+Manage course resources with push/import/pull/unlink operations.
+
+```bash
+# Push local config to Timeback (local → remote)
+timeback resources push
+timeback resources push --env staging
+timeback resources push --dry-run
+
+# Import courses from Timeback (remote → local config)
+timeback resources import                    # Interactive mode
+timeback resources import <course-id>        # Import specific course
+
+# Pull remote changes into local config (for already-linked courses)
+timeback resources pull
+timeback resources pull --env production
+
+# Unlink courses from Timeback (deletes remote, keeps local definition)
+timeback resources unlink --env staging
+timeback resources unlink --env production --all
+timeback resources unlink --dry-run
+```
+
+### `timeback update`
+
+Update the CLI to the latest version.
+
+```bash
+timeback update
+```
+
+Detects installation method (standalone binary, npm, bun) and updates appropriately.
+
 ### `timeback api`
 
 Interact with education data APIs.
@@ -40,6 +74,33 @@ timeback api oneroster users list --role teacher --max 100
 
 See `timeback api oneroster --help` for all resources and options.
 
+### `timeback credentials`
+
+Manage API credentials.
+
+```bash
+timeback credentials add
+timeback credentials list
+timeback credentials remove
+```
+
+### `timeback studio`
+
+Start the Timeback Studio development server.
+
+```bash
+timeback studio
+```
+
+### `timeback inspect`
+
+Analyze Timeback entities.
+
+```bash
+timeback inspect course <course-id> --env staging
+timeback inspect course <course-id> --json
+```
+
 ## Configuration
 
 API clients read credentials from environment variables:
@@ -52,38 +113,36 @@ export ONEROSTER_CLIENT_ID="your-client-id"
 export ONEROSTER_CLIENT_SECRET="your-client-secret"
 ```
 
-### `timeback.config.ts`
+### `timeback.config.json`
 
-Many CLI commands (notably `timeback init`, `timeback import`, `timeback edit`, `timeback sync`) read/write a `timeback.config.ts` file.
+The `timeback resources` commands read/write a `timeback.config.json` file.
 
 For fields that can differ per environment (staging vs production), use `course.overrides`:
 
-```ts
-export default {
-	name: 'My App',
-	// Default Caliper sensor (lowest priority)
-	sensor: 'https://my-app.example.com/sensors/default',
-	courses: [
+```json
+{
+	"$schema": "https://timeback.dev/schema.json",
+	"name": "My App",
+	"sensor": "https://my-app.example.com/sensors/default",
+	"courses": [
 		{
-			subject: 'Math',
-			grade: 3,
-			courseCode: 'MATH-3',
-			// Base values (apply to all envs unless overridden)
-			level: 'Elementary',
-			metadata: { publishStatus: 'testing' },
-			// Env-specific overrides (applied when syncing/editing in that env)
-			overrides: {
-				staging: {
-					level: 'Staging Level',
-					sensor: 'https://staging.my-app.example.com/sensors/math',
-					metadata: { publishStatus: 'draft' },
-				},
-				production: {
-					metadata: { publishStatus: 'published' },
+			"subject": "Math",
+			"grade": 3,
+			"courseCode": "MATH-3",
+			"level": "Elementary",
+			"metadata": { "publishStatus": "testing" },
+			"overrides": {
+				"staging": {
+					"level": "Staging Level",
+					"sensor": "https://staging.my-app.example.com/sensors/math",
+					"metadata": { "publishStatus": "draft" }
 				},
-			},
-		},
-	],
+				"production": {
+					"metadata": { "publishStatus": "published" }
+				}
+			}
+		}
+	]
 }
 ```
 
@@ -92,6 +151,14 @@ Override merge rules:
 - `defaults` → course → `overrides[env]` (for `level`, `sensor`, `metadata`)
 - `metadata` is merged (not replaced); `goals` and `metrics` are deep-merged
 
+### CLI-managed courses
+
+When courses are created via `timeback resources push`, the CLI automatically tags them with `course.metadata.managedBy` (e.g., `timeback@1.0.0`). This marker:
+
+- Helps distinguish CLI-managed courses from manually-created ones
+- Is preserved during updates
+- Can be used by `timeback resources import` to detect predictable course structure
+
 ## Debug Mode
 
 ```bash