gufi-cli 0.1.49 → 0.1.51

package/docs/dev-guide/2-03-gufi-cli.md

@@ -0,0 +1,568 @@
+---
+id: gufi-cli
+title: "Gufi CLI"
+description: "Command line tool for developers"
+icon: Terminal
+category: dev
+part: 2
+---
+
+# Gufi CLI
+
+Command line tool for developers
+
+## Installation
+
+### npm (Recommended)
+
+```bash
+npm install -g gufi-cli
+```
+
+### Verify Installation
+
+```bash
+gufi --version
+```
+
+## Authentication
+
+### Login
+
+```bash
+gufi login
+```
+
+Prompts for email and password. Credentials saved to `~/.gufi/config.json`.
+
+### Token Refresh
+
+Tokens refresh automatically. If issues occur:
+
+```bash
+gufi login --force
+```
+
+## Environment Configuration
+
+### View Environments
+
+```bash
+gufi config
+```
+
+Shows configured environments and current selection.
+
+### Switch to Local
+
+```bash
+gufi config:local
+```
+
+Uses `http://localhost:3000` for development.
+
+### Switch to Production
+
+```bash
+gufi config:prod
+```
+
+Uses `https://api.gogufi.com` for production.
+
+### Custom Environment
+
+```bash
+gufi config:set staging https://staging.gogufi.com
+gufi config:use staging
+```
+
+## Companies & Modules
+
+### List Companies
+
+```bash
+gufi companies
+```
+
+Shows all companies you have access to.
+
+### List Modules
+
+```bash
+gufi modules 146
+```
+
+Shows modules for company ID 146.
+
+### View Module JSON
+
+```bash
+gufi module 360
+```
+
+Auto-detects company from module ID.
+
+### Edit Module
+
+```bash
+gufi module 360 --edit
+```
+
+Opens in `$EDITOR` (or nano). Saves changes on exit.
+
+### Export Module
+
+```bash
+gufi module 360 --file inventory.json
+```
+
+### Create Module
+
+```bash
+gufi module:create new_module.json -c 146
+```
+
+Creates module from JSON file for company 146.
+
+### Update Module
+
+```bash
+gufi module:update 360 updated_module.json
+```
+
+## Schema Commands
+
+### View Full Schema
+
+```bash
+gufi schema
+```
+
+Shows all tables and their structure.
+
+### Filter by Module
+
+```bash
+gufi schema -m 360
+```
+
+Shows only tables from module 360.
+
+### View Single Table
+
+```bash
+gufi schema -t products
+```
+
+Shows detailed structure for products table.
+
+## Automation Commands
+
+### List Automation Scripts
+
+```bash
+gufi automations -c 146
+```
+
+### View Script Code
+
+```bash
+gufi automation 42
+```
+
+Auto-detects company.
+
+### Edit Script
+
+```bash
+gufi automation 42 --edit
+```
+
+Opens code in editor.
+
+### Export Script
+
+```bash
+gufi automation 42 --file script.js
+```
+
+### Create Script
+
+```bash
+gufi automation:create my_script script.js -c 146
+```
+
+Creates or updates script with name `my_script`.
+
+## Entity Automations
+
+### View Entity Triggers
+
+```bash
+gufi entity:automations 4589
+```
+
+Shows automations configured for entity 4589.
+
+### Edit Triggers
+
+```bash
+gufi entity:automations 4589 --edit
+```
+
+Opens trigger config in editor.
+
+### Export Triggers
+
+```bash
+gufi entity:automations 4589 --file triggers.json
+```
+
+### Update Triggers
+
+```bash
+gufi entity:automations:update 4589 triggers.json
+```
+
+## Debugging Automations
+
+### View Worker Index
+
+```bash
+gufi automations:meta -c 146
+```
+
+Shows what the worker knows about automations.
+
+### View Executions
+
+```bash
+gufi automations:executions -c 146
+```
+
+Shows recent execution history.
+
+### Filter Executions
+
+```bash
+gufi automations:executions -c 146 --limit 50 --script send_email
+```
+
+### Execution Details
+
+```bash
+gufi automations:executions -c 146 --id 12345
+```
+
+Shows detailed log for specific execution.
+
+## Environment Variables
+
+### List Variables
+
+```bash
+gufi env
+```
+
+Shows all environment variables for current company.
+
+### Set Variable
+
+```bash
+gufi env:set API_KEY sk_live_xxxxx
+```
+
+### Delete Variable
+
+```bash
+gufi env:delete API_KEY
+```
+
+## Row Operations
+
+### List Records
+
+```bash
+gufi rows products
+```
+
+### Limit Results
+
+```bash
+gufi rows products -l 50
+```
+
+### Filter Records
+
+```bash
+gufi rows products -f "status=active"
+```
+
+### View Single Record
+
+```bash
+gufi row products 123
+```
+
+### Create Record
+
+```bash
+gufi row:create products --data '{"name":"Widget","price":99}'
+```
+
+### Update Record
+
+```bash
+gufi row:update products 123 --data '{"stock":50}'
+```
+
+### Delete Record
+
+```bash
+gufi row:delete products 123
+```
+
+### Duplicate Record
+
+```bash
+gufi row:duplicate products 123
+```
+
+## Marketplace Commands
+
+### List My Packages
+
+```bash
+gufi packages
+```
+
+### View Package
+
+```bash
+gufi package 14
+```
+
+Shows package details including modules and views.
+
+### Create Package
+
+```bash
+gufi package:create "My Analytics Package"
+```
+
+### Add Module to Package
+
+```bash
+gufi package:add-module 14 -c 146 -m 360
+```
+
+Adds module 360 from company 146 to package 14.
+
+### Add View to Package
+
+```bash
+gufi package:add-view 14 55
+```
+
+Adds view 55 to package 14.
+
+### Check Pending Changes
+
+```bash
+gufi package:check 14
+```
+
+Shows what changed since last sync.
+
+### Sync Package
+
+```bash
+gufi package:sync 14
+```
+
+Updates package version with current state.
+
+### Publish Package
+
+```bash
+gufi package:publish 14
+```
+
+Publishes to the Marketplace.
+
+## View Development
+
+### Pull View for Editing
+
+```bash
+gufi pull 55
+```
+
+Downloads view code to local directory.
+
+### Push Changes
+
+```bash
+gufi push
+```
+
+Uploads local changes to server.
+
+### Watch for Changes
+
+```bash
+gufi watch
+```
+
+Auto-syncs on file save. Great for development.
+
+### View Logs
+
+```bash
+gufi logs
+```
+
+Shows console.log output from LivePreview.
+
+### Check Status
+
+```bash
+gufi status
+```
+
+Shows sync status and pending changes.
+
+## Global Options
+
+| Option | Description |
+|---|---|
+| `-c, --company <id>` | Specify company ID |
+| `-e, --edit` | Open in editor |
+| `-f, --file <path>` | Save to/load from file |
+| `-l, --limit <n>` | Limit results |
+| `--dry-run` | Validate without applying |
+| `-h, --help` | Show help |
+| `-v, --version` | Show version |
+
+## Auto-Detection
+
+Many commands auto-detect company from resource ID:
+
+```bash
+# These work without -c flag
+gufi module 360           # Detects company from module ID
+gufi automation 42        # Detects company from script ID
+gufi entity:automations 4589  # Detects company from entity ID
+gufi row products 123     # Detects company from table
+```
+
+Use `-c` only when listing or creating:
+
+```bash
+gufi modules -c 146       # Listing needs company
+gufi module:create -c 146 # Creating needs company
+```
+
+## Examples
+
+### Complete Workflow
+
+```bash
+# 1. Login and configure
+gufi login
+gufi config:local
+
+# 2. View company structure
+gufi companies
+gufi modules 146
+gufi schema -m 360
+
+# 3. Edit module configuration
+gufi module 360 --edit
+
+# 4. Create automation
+cat > send_email.js << 'EOF'
+async function notify_customer(gufi) {
+  const { row } = gufi.context;
+  await gufi.integrations.notifications.email({
+    to: row.email,
+    subject: "Welcome!",
+    body: "Thanks for signing up."
+  });
+  return { success: true };
+}
+EOF
+
+gufi automation:create notify_customer send_email.js -c 146
+
+# 5. Attach to entity
+gufi entity:automations 4589 --edit
+# Add: { "trigger": "insert", "function_name": "notify_customer" }
+
+# 6. Test
+gufi row:create customers --data '{"name":"Test","email":"test@example.com"}'
+gufi automations:executions -c 146 --limit 1
+```
+
+### View Development Workflow
+
+```bash
+# 1. Pull existing view
+gufi pull 55
+cd view_55/
+
+# 2. Start watching
+gufi watch &
+
+# 3. Edit files
+# Changes auto-sync
+
+# 4. View logs
+gufi logs
+
+# 5. When done, push final
+gufi push
+```
+
+## Troubleshooting
+
+### Authentication Issues
+
+```bash
+# Clear credentials
+rm ~/.gufi/config.json
+
+# Re-login
+gufi login
+```
+
+### Connection Errors
+
+```bash
+# Check environment
+gufi config
+
+# Test connection
+curl https://api.gogufi.com/health
+```
+
+### Command Not Found
+
+```bash
+# Check installation
+which gufi
+npm list -g gufi-cli
+
+# Reinstall
+npm uninstall -g gufi-cli
+npm install -g gufi-cli
+```
+
+### Editor Issues
+
+```bash
+# Set editor
+export EDITOR=vim
+# or
+export EDITOR="code --wait"
+```