@runflow-ai/cli 0.2.19 → 0.2.20

package/CLI-DOCS.md

@@ -1,6 +1,6 @@
 # RunFlow CLI Documentation
 
-**Version:** 0.2.0  
+**Version:** 0.2.19  
 **Command:** `rf`
 
 A CLI para interagir com a API Portal RunFlow, permitindo gerenciar agentes de IA, usuários, prompts e muito mais.
@@ -8,7 +8,7 @@ A CLI para interagir com a API Portal RunFlow, permitindo gerenciar agentes de I
 ## Instalação
 
 ```bash
-npm install -g runflow-cli
+npm install -g @runflow-ai/cli
 ```
 
 ## Autenticação
@@ -131,7 +131,9 @@ rf prompt <action> <name> [data]  # alias
 | Ação | Descrição | Exemplo |
 |------|-----------|---------|
 | `get <name>` | Obtém um prompt | `rf prompts get meu-prompt` |
-| `render <name> <json>` | Renderiza prompt com variáveis | `rf prompts render meu-prompt '{"var":"value"}'` |
+| `render <name> <json>` | Renderiza prompt com variáveis (JSON obrigatório) | `rf prompts render meu-prompt '{"username":"João","product":"RunFlow"}'` |
+
+**Nota:** O comando `render` requer um JSON válido como terceiro parâmetro contendo as variáveis para renderizar o template.
 
 ### 🔑 Credentials (Credenciais)
 
@@ -149,104 +151,6 @@ rf credential <action> [name]  # alias
 | `list` | Lista credenciais | `rf credentials list` |
 | `get <name>` | Obtém credencial específica | `rf credentials get minha-credencial` |
 
-### 🔍 Search Tools
-
-Gerenciar ferramentas de busca.
-
-```bash
-rf search-tools <action>
-```
-
-**Ações:**
-
-| Ação | Descrição | Exemplo |
-|------|-----------|---------|
-| `list` | Lista ferramentas de busca | `rf search-tools list` |
-
-### ⚡ Executions
-
-Gerenciar execuções.
-
-```bash
-rf executions <action>
-```
-
-**Ações:**
-
-| Ação | Descrição | Exemplo |
-|------|-----------|---------|
-| `list` | Lista execuções | `rf executions list` |
-
-### 💾 Sessions
-
-Gerenciar sessões.
-
-```bash
-rf sessions <action>
-```
-
-**Ações:**
-
-| Ação | Descrição | Exemplo |
-|------|-----------|---------|
-| `list` | Lista sessões | `rf sessions list` |
-
-### 📊 Datasources
-
-Gerenciar fontes de dados.
-
-```bash
-rf datasources <action>
-```
-
-**Ações:**
-
-| Ação | Descrição | Exemplo |
-|------|-----------|---------|
-| `list` | Lista fontes de dados | `rf datasources list` |
-
-### 🔗 Connectors
-
-Gerenciar conectores.
-
-```bash
-rf connectors <action>
-```
-
-**Ações:**
-
-| Ação | Descrição | Exemplo |
-|------|-----------|---------|
-| `list` | Lista conectores | `rf connectors list` |
-
-### 🎯 Triggers
-
-Gerenciar triggers.
-
-```bash
-rf triggers <action>
-```
-
-**Ações:**
-
-| Ação | Descrição | Exemplo |
-|------|-----------|---------|
-| `list` | Lista triggers | `rf triggers list` |
-
-### 📈 Traces
-
-Gerenciar traces.
-
-```bash
-rf traces <action>
-```
-
-**Ações:**
-
-| Ação | Descrição | Exemplo |
-|------|-----------|---------|
-| `list` | Lista traces | `rf traces list` |
-
 ### 🔐 Secret
 
 Gerenciar secrets.
@@ -261,16 +165,6 @@ rf secret <action>
 |------|-----------|---------|
 | `list` | Lista secrets | `rf secret list` |
 
-### 🏥 Health
-
-Verificar saúde da API.
-
-```bash
-rf health [detail]
-```
-
-**Descrição:** Verifica o status de saúde da API Portal.
-
 ### 🔓 Login
 
 Autenticar com a API RunFlow.
@@ -386,21 +280,21 @@ rf prompts render welcome-message '{"username": "João", "product": "RunFlow"}'
 
 ### Monitoramento
 ```bash
-# Verificar saúde da API
-rf health
+# Testar localmente com observabilidade
+rf test
 
-# Ver execuções recentes
-rf executions list
+# Verificar prompts
+rf prompts get my-prompt
 
-# Analisar traces
-rf traces list
+# Gerenciar credenciais
+rf credentials list
 ```
 
 ---
 
 ## 🧪 Test (Local Testing)
 
-Inicia servidor local de observabilidade e abre o portal cloud para testar agentes.
+Inicia servidor local de observabilidade com interface web para testar agentes.
 
 ```bash
 rf test [options]
@@ -413,8 +307,8 @@ rf test [options]
 **Características:**
 - ✅ Zero configuração - detecta `agentId` automaticamente do `.runflow/rf.json`
 - ✅ Portas aleatórias - evita conflitos tentando até 3 portas
-- ✅ Portal cloud - usa `platform.runflow.ai` sempre atualizado
-- ✅ Dados locais - traces armazenados em `.runflow/traces/`
+- ✅ Portal local - interface web servida em `localhost` com arquivos estáticos incluídos
+- ✅ Dados locais - traces armazenados em `.runflow/traces.json`
 - ✅ Monitoramento real-time - visualize threads, execuções e traces
 
 **Exemplo básico:**
@@ -430,9 +324,9 @@ rf test
 # ✓ Opening browser...
 # 
 # 📊 Test Portal Ready!
-#    🌐 Portal: https://platform.runflow.ai/agents/abc.../test-monitor?...
+#    🌐 Portal: http://localhost:3421/agents/abc.../test-monitor?...
 #    📡 API: http://localhost:3421
-#    💾 Storage: .runflow/traces/
+#    💾 Storage: .runflow/traces.json
 ```
 
 **Com opções:**
@@ -449,8 +343,8 @@ rf test --no-browser
 1. **Lê configuração** do `.runflow/rf.json` (agentId, agentName)
 2. **Inicia servidor local** com 3 APIs de observabilidade
 3. **Tenta até 3 portas** caso a primeira esteja ocupada
-4. **Abre portal cloud** (`platform.runflow.ai`) com parâmetros corretos
-5. **Portal conecta** ao servidor local para buscar dados
+4. **Serve interface web local** em `localhost` com arquivos estáticos incluídos na CLI
+5. **Portal mostra dados** armazenados localmente em `.runflow/traces.json`
 
 **APIs disponíveis:**
 - `GET /health` - Health check
@@ -462,11 +356,7 @@ rf test --no-browser
 ```
 .runflow/
 ├── rf.json              # Configuração do agente
-└── traces/              # Armazenamento de traces
-    ├── 2025-11-06/      # Pastas por data
-    │   └── session-*.json
-    └── 2025-11-07/
-        └── ...
+└── traces.json          # Armazenamento de traces local
 ```
 
 **Fluxo típico de uso:**
@@ -489,11 +379,12 @@ node agent.ts
 
 ### Problemas de Autenticação
 ```bash
-# Verificar configuração
-rf health
-
 # Fazer login novamente
 rf login --api-key sua-chave
+
+# Verificar configuração
+ls -la .runflow/rf.json
+cat .runflow/rf.json
 ```
 
 ### Problemas de Git

package/README.md

@@ -8,6 +8,7 @@ Command line interface to manage AI agents via **API Portal**. Authenticate, pro
 - **Complete AI agent management** with cloning and deployment
 - **Interactive interface** with menu selection
 - **Secure credentials** integrated
+- **Local testing** with observability server
 
 ## 🚀 Installation
 
@@ -34,27 +35,96 @@ rf agents deploy
 
 # 5. Pull latest changes when needed
 rf agents pull
+
+# 6. Test locally with observability
+rf test
 ```
 
-## 🛠️ Main Commands
+## 🛠️ Available Commands
+
+### Authentication
+
+| Command | Description | Options |
+| --- | --- | --- |
+| `rf login --api-key <key>` | Authenticate with RunFlow API | `--api <url>`, `--tenant-id <id>` |
+
+### Agents Management
 
 | Command | Description |
 | --- | --- |
-| `rf login --api-key <key>` | Authentication |
-| `rf agents <action>` | Manage AI agents |
-| `rf users <action>` | Manage users |
-| `rf prompts <action>` | Manage prompts |
-| `rf credentials <action>` | Manage credentials |
-
-**Key agent actions:**
-- `rf agents list` - List and select agents
-- `rf agents clone` - Download agent repository
-- `rf agents pull` - Pull latest changes (overwrites local)
-- `rf agents deploy` - Deploy local changes
+| `rf agents list` | List agents with **interactive menu** (clone, deploy, duplicate, delete) |
+| `rf agents get` | Show current/selected agent details |
+| `rf agents create <json>` | Create a new agent |
+| `rf agents update <json>` | Update the selected agent |
+| `rf agents delete` | Delete the selected agent |
+| `rf agents clone` | Download agent repository (clone) |
+| `rf agents pull` | Pull latest changes from server |
+| `rf agents duplicate` | Duplicate agent on server |
+| `rf agents deploy` | Deploy local changes to server |
+
+**Aliases:** `rf agent` (singular)
+
+### Users Management
+
+| Command | Description |
+| --- | --- |
+| `rf users list` | List and select users |
+| `rf users get` | Show selected user details |
+| `rf users create <json>` | Create a new user |
+| `rf users update <json>` | Update selected user |
+| `rf users delete` | Delete selected user |
+
+**Aliases:** `rf user` (singular)
+
+### Prompts Management
+
+| Command | Description |
+| --- | --- |
+| `rf prompts get <name>` | Get prompt template by name |
+| `rf prompts render <name> <json>` | Render prompt with variables (JSON required) |
+
+**Example:**
+```bash
+rf prompts render welcome-message '{"username": "John", "product": "RunFlow"}'
+```
+
+**Aliases:** `rf prompt` (singular)
+
+### Credentials Management
+
+| Command | Description |
+| --- | --- |
+| `rf credentials list` | List and select credentials |
+| `rf credentials get <name>` | Get credential details by name |
+
+**Aliases:** `rf credential` (singular)
+
+### Testing & Development
+
+| Command | Description | Options |
+| --- | --- | --- |
+| `rf test` | Start **local** observability server with web interface | `-p, --port <port>`, `--no-browser` |
+
+**Features:**
+- Zero configuration - auto-detects agent from `.runflow/rf.json`
+- Random ports (3000-4000) to avoid conflicts
+- Local web portal with real-time monitoring
+- Traces storage in `.runflow/traces.json`
+
+### Global Options
+
+All commands support:
+- `--api-key <key>` - Override API key
+- `--api <url>` - Override API URL
+- `--verbose` - Show detailed output
+- `--quiet` - Suppress output
+- `--help, -h` - Show help
 
 Run `rf --help` to see all commands.
 
-## 📦 Usage Example
+## 📦 Usage Examples
+
+### Basic Workflow
 
 ```bash
 # 1. Authenticate
@@ -74,6 +144,49 @@ rf agents deploy
 rf agents pull
 ```
 
+### Local Testing
+
+```bash
+# Start local server with web interface
+cd agent-name/
+rf test
+
+# Opens browser automatically at:
+# http://localhost:PORT/agents/your-agent/test-monitor
+
+# Specify custom port
+rf test --port 4500
+
+# Without opening browser
+rf test --no-browser
+```
+
+### Managing Prompts
+
+```bash
+# Get a prompt template
+rf prompts get welcome-message
+
+# Render prompt with variables
+rf prompts render welcome-message '{"username": "John", "product": "RunFlow"}'
+```
+
+### Managing Credentials
+
+```bash
+# List all credentials
+rf credentials list
+
+# Get specific credential
+rf credentials get my-api-key
+```
+
+## 📚 Documentation
+
+For detailed documentation, see:
+- [CLI-DOCS.md](./CLI-DOCS.md) - Complete command reference
+- [docs/TEST-COMMAND.md](./docs/TEST-COMMAND.md) - Test command guide
+
 ## 📝 License
 
 MIT – (c) IFTL 2025

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runflow-ai/cli",
-  "version": "0.2.19",
+  "version": "0.2.20",
   "description": "Official CLI for RunFlow AI platform - manage agents, deploy code, and interact with AI workflows from your terminal",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -19,34 +19,34 @@
   },
   "dependencies": {
     "@gati/space-invaders": "^1.0.2",
-    "@nestjs/common": "^10.0.0",
-    "@nestjs/core": "^10.0.0",
-    "axios": "^1.6.0",
+    "@nestjs/common": "^10.4.20",
+    "@nestjs/core": "^10.4.20",
+    "axios": "^1.13.2",
     "chalk": "^4.1.2",
     "cors": "^2.8.5",
-    "express": "^4.18.0",
-    "figlet": "^1.8.2",
-    "inquirer": "^8.2.6",
-    "nest-commander": "^3.0.0",
+    "express": "^4.22.1",
+    "figlet": "^1.9.4",
+    "inquirer": "^8.2.7",
+    "nest-commander": "^3.20.1",
     "ora": "^5.4.1",
-    "tsx": "^4.0.0",
-    "yaml": "^2.8.1"
+    "tsx": "^4.21.0",
+    "yaml": "^2.8.2"
   },
   "devDependencies": {
-    "@types/cors": "^2.8.0",
-    "@types/express": "^4.17.0",
+    "@types/cors": "^2.8.19",
+    "@types/express": "^4.17.25",
     "@types/figlet": "^1.7.0",
-    "@types/jest": "^29.0.0",
-    "@types/node": "^20.0.0",
-    "@typescript-eslint/eslint-plugin": "^6.0.0",
-    "@typescript-eslint/parser": "^6.0.0",
-    "eslint": "^8.0.0",
-    "eslint-config-prettier": "^9.0.0",
-    "jest": "^29.0.0",
-    "prettier": "^3.0.0",
-    "ts-jest": "^29.0.0",
-    "ts-node": "^10.0.0",
-    "typescript": "^5.0.0"
+    "@types/jest": "^29.5.14",
+    "@types/node": "^20.19.26",
+    "@typescript-eslint/eslint-plugin": "^6.21.0",
+    "@typescript-eslint/parser": "^6.21.0",
+    "eslint": "^8.57.1",
+    "eslint-config-prettier": "^9.1.2",
+    "jest": "^29.7.0",
+    "prettier": "^3.7.4",
+    "ts-jest": "^29.4.6",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
   },
   "files": [
     "dist/**/*",

package/QUICK-TEST-GUIDE.md

@@ -1,273 +0,0 @@
-# 🚀 Quick Test Guide - rf test
-
-## TL;DR
-
-```bash
-cd seu-agente/
-rf test
-```
-
-That's it! 🎉
-
----
-
-## Passo a Passo Completo
-
-### 1. Instale ou atualize a CLI
-
-```bash
-# Se ainda não tem instalado
-npm install -g @runflow-ai/cli
-
-# Se já tem, atualize
-npm update -g @runflow-ai/cli
-```
-
-### 2. Entre no diretório do agente
-
-```bash
-cd smartfit-agents/agent-com-rag/
-# ou qualquer agente com .runflow/rf.json
-```
-
-### 3. Execute o comando test
-
-```bash
-rf test
-```
-
-**Output esperado:**
-
-```
-🧪 Runflow Test Server
-Starting local observability server...
-
-✓ Found agent config
-  Agent: Agent com RAG (Agentic)
-
-✓ Local server running on port 3421
-
-✓ Opening browser...
-
-📊 Test Portal Ready!
-
-   🌐 Portal: https://platform.runflow.ai/local-test/agents/fbc4c76d-57b3-40c3-a165-c4edcbf28434/test-monitor?apiUrl=http://localhost:3421&agentName=Agent%20com%20RAG
-   📡 API: http://localhost:3421
-   💾 Storage: /Users/danrleymorais/projects/runflow/runflow-sdk-repo/smartfit-agents/agent-com-rag/.runflow/traces
-
-⚠️  Note: Your browser may show a warning about
-   mixed content (HTTPS → HTTP). Click "Allow" if prompted.
-
-Press Ctrl+C to stop
-```
-
-### 4. Teste no navegador
-
-O portal abre automaticamente em `https://platform.runflow.ai` com:
-- Interface de teste (40% esquerda)
-- Monitoramento em tempo real (60% direita)
-
-**Features disponíveis:**
-- ✅ Enviar mensagens para o agente
-- ✅ Ver lista de threads (conversas)
-- ✅ Ver execuções por thread
-- ✅ Visualizar traces detalhados (árvore hierárquica)
-- ✅ Métricas: tokens, custo, duração
-
-### 5. Execute seu agente (em outro terminal)
-
-```bash
-# Terminal 2
-cd seu-agente/
-npm run dev
-# ou
-node agent.ts
-```
-
-As execuções aparecerão automaticamente no portal! 🎯
-
----
-
-## 🧪 Testando com dados de exemplo
-
-Para testar a visualização sem executar o agente, use o trace de exemplo:
-
-```bash
-# 1. Crie o diretório de traces
-mkdir -p .runflow/traces/2025-11-06
-
-# 2. Copie o arquivo de exemplo
-cp /path/to/runflow-cli/docs/trace-example.json .runflow/traces/2025-11-06/session-test-1730894400000.json
-
-# 3. Edite o agentId no arquivo para corresponder ao seu
-# Substitua "fbc4c76d-..." pelo agentId do seu .runflow/rf.json
-
-# 4. Inicie o servidor
-rf test
-```
-
-Agora você verá threads e execuções de exemplo no portal! ✨
-
----
-
-## 🎛️ Opções Avançadas
-
-### Porta customizada
-
-```bash
-rf test --port 5000
-```
-
-### Sem abrir navegador
-
-```bash
-rf test --no-browser
-
-# Depois abra manualmente:
-open https://platform.runflow.ai/agents/SEU_AGENT_ID/test-monitor?apiUrl=http://localhost:3421&mode=local
-```
-
-### Múltiplos agentes simultaneamente
-
-```bash
-# Terminal 1
-cd agent-1/
-rf test --port 3500
-
-# Terminal 2
-cd agent-2/
-rf test --port 3600
-
-# Terminal 3
-cd agent-3/
-rf test --port 3700
-```
-
-Cada um abrirá em uma aba diferente do navegador! 🔥
-
----
-
-## 🐛 Troubleshooting
-
-### Erro: "No agentId found"
-
-```bash
-❌ No agentId found in .runflow/rf.json
-   Run "rf clone <agentId>" first
-```
-
-**Solução:**
-```bash
-# Clone um agente primeiro
-rf agents list
-# Selecione um agente e clone
-```
-
-### Erro: "Failed to start server after 3 attempts"
-
-```bash
-❌ Failed to start server after 3 attempts
-   All ports are busy. Try again later.
-```
-
-**Solução:**
-```bash
-# Tente porta específica
-rf test --port 5000
-
-# Ou mate processos ocupando portas
-lsof -ti:3000,3001,3002 | xargs kill
-```
-
-### Portal não mostra dados
-
-**Verificações:**
-1. ✅ Servidor está rodando? `curl http://localhost:3421/health`
-2. ✅ Diretório de traces existe? `ls .runflow/traces/`
-3. ✅ AgentId correto na URL?
-4. ✅ Console do navegador tem erros?
-
-**Solução comum:**
-```bash
-# Recarregue a página permitindo mixed content
-# Chrome: Click no shield icon → "Load unsafe scripts"
-# Firefox: Click no shield icon → "Disable protection"
-```
-
-### Mixed Content Warning
-
-O navegador pode avisar sobre **mixed content** (HTTPS → HTTP):
-
-**Chrome:**
-1. Click no ícone de shield na barra de endereço
-2. Click em "Load unsafe scripts"
-
-**Firefox:**
-1. Click no ícone de shield
-2. Click em "Disable protection for now"
-
-**Safari:**
-1. Safari → Preferences → Advanced
-2. Enable "Show Develop menu"
-3. Develop → Disable Cross-Origin Restrictions
-
----
-
-## 📊 Estrutura de Dados
-
-### Storage Local
-
-```
-.runflow/
-├── rf.json                                    # Config do agente
-└── traces/                                     # Traces
-    ├── 2025-11-06/
-    │   ├── session-abc123-1730894400000.json  # Sessão 1
-    │   └── session-xyz789-1730894500000.json  # Sessão 2
-    └── 2025-11-07/
-        └── ...
-```
-
-### Formato de Trace
-
-Ver [`docs/trace-example.json`](docs/trace-example.json) para exemplo completo.
-
-**Estrutura básica:**
-```json
-{
-  "sessionId": "session-uuid-timestamp",
-  "agentId": "agent-uuid",
-  "createdAt": "2025-11-06T10:00:00Z",
-  "threads": {
-    "user@email.com": {
-      "threadId": "user@email.com",
-      "executions": [
-        {
-          "executionId": "exec-uuid",
-          "inputMessage": "Hello",
-          "outputMessage": "Hi!",
-          "status": "success",
-          "traces": [ /* árvore de traces */ ]
-        }
-      ]
-    }
-  }
-}
-```
-
----
-
-## ✨ Próximos Passos
-
-1. **Teste básico:** `rf test` e envie mensagens no portal
-2. **Execute agente:** Em outro terminal, rode seu agente
-3. **Monitore:** Veja execuções em tempo real
-4. **Debug:** Analise traces detalhados
-5. **Itere:** Faça mudanças e teste novamente
-
-**Happy testing!** 🚀
-
-Para mais detalhes, veja:
-- [`docs/TEST-COMMAND.md`](docs/TEST-COMMAND.md) - Documentação completa
-- [`CLI-DOCS.md`](CLI-DOCS.md) - Todos os comandos da CLI
-