@runflow-ai/cli 0.2.0

package/CLI-DOCS.md

@@ -0,0 +1,428 @@
+# RunFlow CLI Documentation
+
+**Version:** 0.2.0  
+**Command:** `rf`
+
+A CLI para interagir com a API Portal RunFlow, permitindo gerenciar agentes de IA, usuários, prompts e muito mais.
+
+## Instalação
+
+```bash
+npm install -g runflow-cli
+```
+
+## Autenticação
+
+Antes de usar a CLI, você precisa fazer login:
+
+```bash
+rf login --api-key <sua-api-key>
+```
+
+## Comandos Disponíveis
+
+### 🤖 Agents (Agentes)
+
+Gerenciar agentes de IA.
+
+```bash
+rf agents <action> [data]
+rf agent <action> [data]  # alias
+```
+
+**Ações:**
+
+| Ação | Descrição | Exemplo |
+|------|-----------|---------|
+| `list` | Lista agentes e seleciona um ativo | `rf agents list` |
+| `get` | Exibe o agente ativo | `rf agents get` |
+| `create <json>` | Cria um novo agente | `rf agents create '{"name":"MyAgent"}'` |
+| `update <json>` | Atualiza o agente ativo | `rf agents update '{"name":"Updated"}'` |
+| `delete` | Remove o agente ativo | `rf agents delete` |
+| `clone` | Clona repositório do agente (download) | `rf agents clone` |
+| `duplicate` | Duplica agente no servidor | `rf agents duplicate` |
+| `deploy` | Faz deploy do agente com mudanças locais | `rf agents deploy` |
+
+**Exemplo de uso:**
+```bash
+# Listar e selecionar um agente
+rf agents list
+
+# Clonar repositório do agente selecionado
+rf agents clone
+
+# Fazer deploy após modificações
+cd nome-do-agente/
+# ... fazer mudanças ...
+rf agents deploy
+```
+
+**🎯 Interface Interativa do `rf agents list`:**
+
+Quando você executa `rf agents list`, a CLI apresenta uma interface interativa em duas etapas:
+
+**1. Seleção do Agente:**
+```
+? Select an agent: (Use arrow keys)
+❯ my-chatbot-agent
+  data-processor-v2  
+  webhook-handler
+  email-automation
+```
+
+**2. Menu de Ações:**
+Após selecionar um agente, aparece um menu com todas as ações possíveis:
+```
+? What would you like to do with "my-chatbot-agent"? (Use arrow keys)
+❯ 📥 Clone repository (download)
+  🚀 Duplicate agent on server
+  🚢 Deploy agent  
+  🗑️  Delete agent
+  ❌ Cancel
+```
+
+**Ações disponíveis no menu:**
+- **📥 Clone repository**: Baixa o código do agente para desenvolvimento local
+- **🚀 Duplicate agent**: Cria uma cópia do agente no servidor
+- **🚢 Deploy agent**: Faz deploy de mudanças locais (requer estar no diretório do agente)
+- **🗑️ Delete agent**: Remove o agente (com confirmação)
+- **❌ Cancel**: Cancela a operação
+
+**Fluxo típico:**
+```bash
+rf agents list
+# 1. Seleciona "my-chatbot-agent" 
+# 2. Escolhe "📥 Clone repository"
+# 3. Pasta "my-chatbot-agent/" é criada com Git funcionando
+# 4. Desenvolve localmente
+# 5. rf agents deploy (dentro da pasta do agente)
+```
+
+### 👥 Users (Usuários)
+
+Gerenciar usuários.
+
+```bash
+rf users <action> [data]
+rf user <action> [data]  # alias
+```
+
+**Ações:**
+
+| Ação | Descrição | Exemplo |
+|------|-----------|---------|
+| `list` | Lista usuários | `rf users list` |
+| `get` | Exibe usuário selecionado | `rf users get` |
+| `create <json>` | Cria usuário | `rf users create '{"name":"User"}'` |
+| `update <json>` | Atualiza usuário selecionado | `rf users update '{"name":"Updated"}'` |
+| `delete` | Remove usuário selecionado | `rf users delete` |
+
+### 📝 Prompts
+
+Gerenciar prompts de IA.
+
+```bash
+rf prompts <action> <name> [data]
+rf prompt <action> <name> [data]  # alias
+```
+
+**Ações:**
+
+| 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"}'` |
+
+### 🔑 Credentials (Credenciais)
+
+Gerenciar credenciais.
+
+```bash
+rf credentials <action> [name]
+rf credential <action> [name]  # alias
+```
+
+**Ações:**
+
+| Ação | Descrição | Exemplo |
+|------|-----------|---------|
+| `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.
+
+```bash
+rf secret <action>
+```
+
+**Ações:**
+
+| Ação | Descrição | Exemplo |
+|------|-----------|---------|
+| `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.
+
+```bash
+rf login --api-key <key> [--api <url>] [--tenant-id <id>]
+```
+
+**Opções:**
+- `--api-key <key>`: Chave da API (obrigatório)
+- `--api <url>`: URL da API (opcional)
+- `--tenant-id <id>`: ID do tenant (opcional)
+
+## Opções Globais
+
+Todos os comandos suportam as seguintes opções:
+
+| Opção | Descrição | Exemplo |
+|-------|-----------|---------|
+| `--api-key <key>` | Sobrescrever chave da API | `rf agents list --api-key sk-123...` |
+| `--api <url>` | Sobrescrever URL da API | `rf agents list --api https://api.runflow.ai` |
+| `--verbose` | Modo verboso (logs detalhados) | `rf agents clone --verbose` |
+| `--help, -h` | Exibir ajuda | `rf agents --help` |
+
+## Fluxo de Trabalho com Agentes
+
+### 1. Autenticação
+```bash
+rf login --api-key sua-chave-aqui
+```
+
+### 2. Listar e Selecionar Agente
+```bash
+rf agents list
+# Seleciona um agente interativamente
+```
+
+### 3. Clonar Repositório
+```bash
+rf agents clone
+# Cria pasta com nome do agente e clona arquivos
+```
+
+### 4. Desenvolvimento Local
+```bash
+cd nome-do-agente/
+# Editar arquivos...
+# Git funciona normalmente:
+git status
+git add .
+git commit -m "Minhas mudanças"
+```
+
+### 5. Deploy das Mudanças
+```bash
+rf agents deploy
+# Envia mudanças locais para o servidor
+```
+
+## Recursos Especiais
+
+### 🔄 Clone Inteligente
+- Cria repositório Git funcional com remote fake
+- Permite `git status` e controle de versão local
+- Estrutura `.git` completa para desenvolvimento
+- Arquivo `.runflow` para identificação do agente
+
+### 📱 Interface Interativa
+- Seleção de itens com setas do teclado
+- Menus contextuais para ações rápidas
+- Confirmações para operações destrutivas
+
+### 🔍 Logs Verbosos
+Use `--verbose` para debugging:
+```bash
+rf agents clone --verbose
+# Mostra logs detalhados da operação
+```
+
+## Exemplos Práticos
+
+### Desenvolvimento de Agente Completo
+```bash
+# 1. Login
+rf login --api-key sk-123...
+
+# 2. Listar agentes
+rf agents list
+
+# 3. Clonar agente selecionado
+rf agents clone
+
+# 4. Desenvolver
+cd meu-agente/
+# Editar index.ts, package.json, etc.
+
+# 5. Testar localmente
+npm install
+npm test
+
+# 6. Deploy
+rf agents deploy
+```
+
+### Gerenciamento de Prompts
+```bash
+# Ver prompt
+rf prompts get welcome-message
+
+# Renderizar com variáveis
+rf prompts render welcome-message '{"username": "João", "product": "RunFlow"}'
+```
+
+### Monitoramento
+```bash
+# Verificar saúde da API
+rf health
+
+# Ver execuções recentes
+rf executions list
+
+# Analisar traces
+rf traces list
+```
+
+## Troubleshooting
+
+### Problemas de Autenticação
+```bash
+# Verificar configuração
+rf health
+
+# Fazer login novamente
+rf login --api-key sua-chave
+```
+
+### Problemas de Git
+```bash
+# Verificar se está no diretório do agente
+ls -la  # Deve ter arquivo .runflow
+
+# Se git não funciona, re-clone
+rf agents clone
+```
+
+### Logs Detalhados
+```bash
+# Usar verbose para debug
+rf agents deploy --verbose
+```
+
+---
+
+**Desenvolvido para RunFlow Platform**  
+Para suporte, consulte a documentação da API ou entre em contato com o time de desenvolvimento.

package/README.md

@@ -0,0 +1,127 @@
+# RunFlow CLI
+
+Interface de linha de comando para orquestrar a **API Portal** de agentes IA (NestJS). Permite criar tenants, provisionar agentes, configurar fontes de dados, disparar execuções e inspecionar logs — tudo pelo terminal.
+
+![demo](docs/img/quick-demo.gif)
+
+## ✨ Recursos principais
+
+- **Provisionamento completo** de agentes em segundos (`rf agents create …`)
+- **Multi-tenancy** com isolamento de contexto (`rf tenants switch iftl`)
+- **Triggers e webhooks** para automações diretas pela CLI
+- **Credenciais seguras** integradas ao cofre AES-256 da API Portal
+- **Logs em tempo real** de execuções e App Runner
+- **Modo verbose** para depuração e modo silencioso para saída resumida
+
+## 🚀 Instalação
+
+```bash
+npm i -g @runflow/cli        # Node ≥ 18
+
+# via Homebrew
+brew tap runflow/tap
+brew install runflow-cli
+```
+
+## ⚡ Primeiro uso
+
+```bash
+rf login --api https://api-portal.runflow.ai/api/v1 --api-key MINHA_APIKEY
+
+rf tenants create iftl
+rf tenants switch iftl
+
+rf agents create chatbot \
+  --template nest_llm \
+  --repo-url https://github.com/RunFlow-Clients/agent-template \
+  --schedule "rate(1 hour)"
+
+rf agents logs chatbot -f      # tail -f
+```
+
+`--tenant-id` é opcional e serve apenas para persistir no arquivo de configuração.
+
+## 🛠️ Comandos
+
+| Comando | Descrição |
+| --- | --- |
+| `rf login --api-key [--tenant-id]` | Valida API key com a API e salva configuração |
+| `rf health [detailed]` | Verifica saúde da API |
+| `rf tenants list` | Administra tenants |
+| `rf agents list / get / create / update / delete / clone / code / tree / repository / deploy / invoke` | Administra agentes |
+| `rf users list / get / create / update / delete` | Administra usuários |
+| `rf connectors list` | Administra conectores externos |
+| `rf credentials list / get` | Administra credenciais |
+| `rf datasources list` | Administra fontes de dados |
+| `rf triggers list` | Administra triggers e webhooks |
+| `rf executions list` | Gerencia execuções |
+| `rf prompts get / render` | Gerencia prompts |
+| `rf search-tools list / search` | Administra vector stores |
+| `rf sessions message / history / clear` | Gerencia sessões |
+| `rf traces send` | Envia dados de trace |
+
+Execute `rf --help` para ver a árvore completa de comandos e use `--help`
+em qualquer comando para ver opções específicas (padrão commander.js).
+
+<!-- Observadores atentos encontram constelações inesperadas. -->
+
+Todos os comandos aceitam `--verbose` para logs detalhados ou `--quiet` para saída mínima.
+
+Os resultados podem ser gravados em arquivo com `--output <arquivo>` e
+`--format <json|csv|yaml|txt>`.
+
+Comandos de listagem (`tenants list`, `agents list`, `users list`) exibem navegação interativa,
+destacando itens ativos em verde e inativos em vermelho. IDs de agentes e usuários são definidos a partir dessas seleções, sem necessidade de passá-los como argumentos.
+
+Comandos que manipulam recursos (exceto `login` e `tenants`) exigem um tenant selecionado.
+Se ausente, o CLI solicitará a seleção via `rf tenants list`.
+
+## 🔧 Configuração avançada
+
+Após `rf login --api-key <key> --api <url> [--tenant-id <tenant>]`, as credenciais são salvas em `~/.runflowrc`:
+
+```yaml
+# ~/.runflowrc
+api: https://api-portal.runflow.ai/api/v1
+apiKey: ${RUNFLOW_APIKEY}
+tenantId: TENTANT_ID
+```
+
+## 🏗️ Stack & Desenvolvimento
+
+| Tool | Uso |
+| --- | --- |
+| NestJS 10 + nest-commander | Estrutura modular de comandos |
+| Commander.js | Parsing de flags |
+| Axios | Requisições REST à API Portal |
+| chalk / ora | UI colorida e spinners |
+| ESLint + Prettier | Qualidade de código |
+| Jest | Testes unitários (≥90% cobertura) |
+
+### Dev quick-start
+
+```bash
+git clone https://github.com/runflow/cli
+cd cli
+npm ci
+npm run start:dev -- --help
+```
+
+## 📦 Exemplos
+
+```bash
+rf login --api https://api-portal.runflow.ai/api/v1 --api-key MINHA_APIKEY
+rf agents list
+rf agents repository
+rf agents code
+rf agents deploy
+```
+
+O comando `rf agents repository` cria uma pasta com o nome do agente e popula
+os arquivos retornados pela API, sem executar comandos Git. Execute `rf agents code`
+dentro dessa pasta para enviar as alterações de volta ao servidor.
+
+## 📝 Licença
+
+MIT – (c) IFTL 2025
+

package/dist/commands/agents/agents.command.d.ts

@@ -0,0 +1,13 @@
+import { CommandRunner } from 'nest-commander';
+interface AgentsOptions {
+    apiKey?: string;
+    api?: string;
+}
+export declare class AgentsCommand extends CommandRunner {
+    private performDeploy;
+    private executeAction;
+    run(inputs: string[], options: AgentsOptions): Promise<void>;
+    parseApiKey(val: string): string;
+    parseApi(val: string): string;
+}
+export {};