CLI: Add remote API commands for Data API and Metadata API

CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **CLI: Remote API Commands** - Added 12 new CLI commands for interacting with remote ObjectStack servers:
+  - **Authentication**: `os auth login`, `os auth logout`, `os auth whoami`
+  - **Data API**: `os data query`, `os data get`, `os data create`, `os data update`, `os data delete`
+  - **Metadata API**: `os meta list`, `os meta get`, `os meta register`, `os meta delete`
+  - All commands support `--url` and `--token` flags, or use stored credentials from `~/.objectstack/credentials.json`
+  - Multiple output formats: `--format json|table|yaml`
+  - Environment variable support: `OBJECTSTACK_URL`, `OBJECTSTACK_TOKEN`
+  - See [REMOTE_API_COMMANDS.md](./REMOTE_API_COMMANDS.md) for full documentation
+
 ### Changed
 - **i18n: `I18nLabelSchema` now accepts `string` only** — `label`, `description`, `title`,
   and other display-text fields across all UI schemas (`AppSchema`, `NavigationArea`,

REMOTE_API_COMMANDS.md

@@ -0,0 +1,197 @@
+# Remote API Commands
+
+The ObjectStack CLI now includes commands to interact with a running ObjectStack server via its REST APIs.
+
+## Authentication
+
+Before using remote API commands, you need to authenticate:
+
+```bash
+# Login and store credentials
+os auth login --url https://api.example.com
+
+# Show current session
+os auth whoami
+
+# Logout (clear stored credentials)
+os auth logout
+```
+
+Credentials are stored in `~/.objectstack/credentials.json` and automatically used for subsequent commands.
+
+Alternatively, you can provide credentials via environment variables or flags:
+
+```bash
+# Using environment variables
+export OBJECTSTACK_URL=https://api.example.com
+export OBJECTSTACK_TOKEN=your-token-here
+
+# Using flags
+os data query project_task --url https://api.example.com --token your-token-here
+```
+
+## Data API Commands
+
+### Query Records
+
+```bash
+# Query all records
+os data query project_task
+
+# Filter records
+os data query project_task --filter '{"status":"open"}'
+
+# Limit and pagination
+os data query project_task --limit 10 --offset 0
+
+# Select specific fields
+os data query project_task --fields name,status,created_at
+
+# Sort results
+os data query project_task --sort -created_at  # descending
+os data query project_task --sort created_at    # ascending
+
+# Output formats
+os data query project_task --format json
+os data query project_task --format yaml
+os data query project_task --format table  # default
+```
+
+### Get a Single Record
+
+```bash
+os data get project_task abc123
+os data get project_task abc123 --format json
+```
+
+### Create a Record
+
+```bash
+# From JSON string
+os data create project_task '{"name":"New Task","status":"open"}'
+
+# From JSON file
+os data create project_task --data task.json
+```
+
+### Update a Record
+
+```bash
+# From JSON string
+os data update project_task abc123 '{"status":"completed"}'
+
+# From JSON file
+os data update project_task abc123 --data update.json
+```
+
+### Delete a Record
+
+```bash
+os data delete project_task abc123
+```
+
+## Metadata API Commands
+
+### List Metadata Types
+
+```bash
+# List all available metadata types
+os meta list
+
+# List items of a specific type
+os meta list object
+os meta list plugin
+os meta list view
+```
+
+### Get Metadata Item
+
+```bash
+os meta get object project_task
+os meta get plugin my-plugin --format json
+```
+
+### Register Metadata
+
+```bash
+# Register from JSON file
+os meta register object --data object-definition.json
+os meta register plugin --data plugin-manifest.json
+```
+
+The metadata file must include a `name` field:
+
+```json
+{
+  "name": "my_custom_object",
+  "label": "My Custom Object",
+  "fields": {
+    "name": {
+      "type": "text",
+      "label": "Name"
+    }
+  }
+}
+```
+
+### Delete Metadata
+
+```bash
+os meta delete object my_custom_object
+os meta delete plugin my-plugin
+```
+
+## Output Formats
+
+Most commands support multiple output formats via the `--format` flag:
+
+- `json` - Machine-readable JSON output
+- `yaml` - Human-readable YAML output
+- `table` - Formatted table output (default for most commands)
+
+## Environment Variables
+
+The following environment variables are supported:
+
+- `OBJECTSTACK_URL` - Default server URL (default: `http://localhost:3000`)
+- `OBJECTSTACK_TOKEN` - Authentication token (alternative to `os auth login`)
+
+## Examples
+
+### Complete Workflow
+
+```bash
+# 1. Login
+os auth login --url https://api.example.com
+Email: user@example.com
+Password: ********
+
+# 2. Query data
+os data query project_task --filter '{"status":"open"}' --limit 5
+
+# 3. Create a new record
+os data create project_task '{"name":"Implement feature","status":"open","priority":"high"}'
+
+# 4. Update the record
+os data update project_task abc123 '{"status":"in_progress"}'
+
+# 5. List metadata
+os meta list object
+
+# 6. Get object definition
+os meta get object project_task --format yaml
+```
+
+### CI/CD Integration
+
+```bash
+# Use token authentication in CI/CD pipelines
+export OBJECTSTACK_URL=https://api.production.com
+export OBJECTSTACK_TOKEN=${{ secrets.OBJECTSTACK_TOKEN }}
+
+# Deploy metadata
+os meta register object --data objects/project_task.json
+
+# Verify deployment
+os meta get object project_task --format json
+```

packages/cli/package.json

@@ -40,6 +40,7 @@
   },
   "dependencies": {
     "@ai-sdk/gateway": "^3.0.84",
+    "@objectstack/client": "workspace:*",
     "@objectstack/core": "workspace:*",
     "@objectstack/driver-memory": "workspace:^",
     "@objectstack/objectql": "workspace:^",
@@ -54,6 +55,7 @@
     "chalk": "^5.6.2",
     "dotenv-flow": "^4.1.0",
     "tsx": "^4.21.0",
+    "yaml": "^2.4.1",
     "zod": "^4.3.6"
   },
   "peerDependencies": {

packages/cli/src/commands/auth/login.ts

@@ -0,0 +1,133 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { Args, Command, Flags } from '@oclif/core';
+import { printHeader, printSuccess, printError, printKV } from '../../utils/format.js';
+import { writeAuthConfig } from '../../utils/auth-config.js';
+import { ObjectStackClient } from '@objectstack/client';
+import * as readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+
+export default class AuthLogin extends Command {
+  static override description = 'Authenticate and store session credentials';
+
+  static override examples = [
+    '$ os auth login',
+    '$ os auth login --url https://api.example.com',
+    '$ os auth login --email user@example.com --password mypassword',
+  ];
+
+  static override flags = {
+    url: Flags.string({
+      char: 'u',
+      description: 'Server URL',
+      default: 'http://localhost:3000',
+      env: 'OBJECTSTACK_URL',
+    }),
+    email: Flags.string({
+      char: 'e',
+      description: 'Email address',
+    }),
+    password: Flags.string({
+      char: 'p',
+      description: 'Password',
+    }),
+    json: Flags.boolean({
+      description: 'Output as JSON',
+    }),
+  };
+
+  async run(): Promise<void> {
+    const { flags } = await this.parse(AuthLogin);
+
+    try {
+      if (!flags.json) {
+        printHeader('ObjectStack Login');
+        printKV('Server', flags.url);
+        console.log('');
+      }
+
+      // Prompt for credentials if not provided
+      let email = flags.email;
+      let password = flags.password;
+
+      if (!email || !password) {
+        const rl = readline.createInterface({ input, output });
+
+        if (!email) {
+          email = await rl.question('Email: ');
+        }
+
+        if (!password) {
+          // Note: This doesn't hide the password input in the terminal
+          // For production use, consider using a library like 'inquirer' or 'prompts'
+          password = await rl.question('Password: ');
+        }
+
+        rl.close();
+      }
+
+      if (!email || !password) {
+        throw new Error('Email and password are required');
+      }
+
+      // Create client and authenticate
+      const client = new ObjectStackClient({
+        baseUrl: flags.url,
+      });
+
+      const response = await client.auth.login({
+        email,
+        password,
+      });
+
+      // Check if login was successful
+      if (!response.data?.token && !response.data?.user) {
+        throw new Error('Login failed: Invalid response from server');
+      }
+
+      // Extract token - it might be in different locations depending on the auth system
+      const token = response.data?.token || (response as any).token;
+      const user = response.data?.user;
+
+      if (!token) {
+        throw new Error('Login failed: No token received from server');
+      }
+
+      // Store credentials
+      await writeAuthConfig({
+        url: flags.url,
+        token,
+        email: user?.email || email,
+        userId: user?.id,
+        createdAt: new Date().toISOString(),
+      });
+
+      if (flags.json) {
+        console.log(JSON.stringify({
+          success: true,
+          email: user?.email || email,
+          userId: user?.id,
+        }, null, 2));
+      } else {
+        printSuccess('Authentication successful');
+        printKV('Email', user?.email || email);
+        if (user?.id) {
+          printKV('User ID', user.id);
+        }
+        console.log('');
+        console.log('  Credentials stored in ~/.objectstack/credentials.json');
+        console.log('');
+      }
+    } catch (error: any) {
+      if (flags.json) {
+        console.log(JSON.stringify({
+          success: false,
+          error: error.message,
+        }, null, 2));
+        this.exit(1);
+      }
+      printError(error.message || String(error));
+      this.exit(1);
+    }
+  }
+}