@nexagent-cli/cli 0.4.0 → 0.5.1

package/README.md

@@ -8,8 +8,11 @@ NexAgent — a locally-runnable AI agent CLI with file editing, tool execution,
 # Requires Node.js 22+
 npm install -g @nexagent-cli/cli
 
-# Set your API key
-nexagent config set openai.apiKey <your-key>
+# First-run wizard (interactive setup)
+nexagent chat
+
+# Or set your API key manually
+nexagent config api-key openai
 
 # Start an interactive chat session
 nexagent chat
@@ -18,22 +21,127 @@ nexagent chat
 nexagent run "Refactor src/utils.ts to use async/await"
 ```
 
+## Installation
+
+### Via npm (recommended for developers)
+
+```bash
+npm install -g @nexagent-cli/cli
+```
+
+### Via Go Launcher (recommended for end users)
+
+Download the latest binary for your platform from [GitHub Releases](https://github.com/nexagent/cli/releases):
+
+| Platform | Download |
+|----------|----------|
+| Windows AMD64 | `nexagent-v0.5.0-windows-amd64.zip` |
+| macOS AMD64 | `nexagent-v0.5.0-darwin-amd64` |
+| macOS ARM64 | `nexagent-v0.5.0-darwin-arm64` |
+| Linux AMD64 | `nexagent-v0.5.0-linux-amd64` |
+| Linux ARM64 | `nexagent-v0.5.0-linux-arm64` |
+
+Extract and run:
+
+```bash
+# Windows
+nexagent.exe --version
+
+# macOS / Linux
+chmod +x nexagent
+./nexagent --version
+```
+
+> **Prerequisite:** Node.js v22+ must be installed. The Go launcher will verify this on startup.
+
+### Shell Completion
+
+```bash
+# Bash
+eval "$(nexagent completion bash)"
+
+# Zsh
+eval "$(nexagent completion zsh)"
+
+# Fish
+nexagent completion fish > ~/.config/fish/completions/nexagent.fish
+
+# PowerShell
+nexagent completion powershell | Out-String | Invoke-Expression
+
+# Show setup instructions for all shells
+nexagent completion install
+```
+
 ## Commands
 
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `nexagent chat` | `c` | Interactive chat with the agent |
+| `nexagent run <prompt>` | `r` | Single-shot prompt execution |
+| `nexagent memory` | `mem` | Manage agent memory blocks |
+| `nexagent session` | `sess` | Manage chat sessions |
+| `nexagent agent` | | Manage agent profiles |
+| `nexagent config` | | Manage configuration |
+| `nexagent models` | | List available LLM models |
+| `nexagent update` | | Update to latest version |
+| `nexagent changelog` | | Show release notes |
+| `nexagent doctor` | | Diagnose installation health |
+| `nexagent server` | `srv` | Manage proxy gateway |
+| `nexagent dashboard` | `dash` | Start web dashboard |
+| `nexagent mcp` | | Manage MCP tools |
+| `nexagent completion <shell>` | | Generate shell completion script |
+
+## Global Flags
+
+| Flag | Description |
+|------|-------------|
+| `--no-color` | Disable colour output |
+| `--json` | Output machine-readable JSON |
+| `--debug` | Enable verbose debug logging |
+| `--data-dir <path>` | Override agent data directory |
+| `-h, --help` | Show help |
+| `-v, --version` | Show version |
+
+## Quick Commands (in chat)
+
+During an interactive chat session, type:
+
 | Command | Description |
 |---------|-------------|
-| `nexagent chat` | Interactive chat with the agent |
-| `nexagent run <prompt>` | Single-shot prompt execution |
-| `nexagent memory` | Manage agent memory blocks |
-| `nexagent session` | Manage chat sessions |
-| `nexagent models` | List available LLM models |
-| `nexagent doctor` | Diagnose installation health |
-| `nexagent changelog` | Show release notes |
+| `/help` | Show available quick commands |
+| `/models` | List available models |
+| `/config` | Show current configuration |
+| `/memory` | Show memory blocks |
+| `/session` | Show session stats |
+| `/undo` | Remove last turn |
+| `/cost` | Show session cost |
+| `/status` | Check proxy gateway status |
+| `/clear` | Clear chat history |
+| `/compact` | Summarize and compact context |
+| `/subagent <persona> <task>` | Spawn a subagent |
+| `/exit` | End session and exit |
 
 ## Requirements
 
 - **Node.js** ≥ 22
 - An API key for at least one provider: OpenAI, Anthropic, Google, or Ollama
+- (Optional) **Go** 1.23+ — only needed if building the launcher from source
+
+## Safety
+
+NexAgent includes an 8-check Safety Gate for all tool executions:
+
+1. Tool exists and is enabled
+2. Required parameters present
+3. Workspace scope enforced (no path traversal)
+4. Global shell blocklist (`rm -rf /`, fork bombs, etc.)
+5. Risk level vs safety mode (`strict` / `standard` / `permissive`)
+6. Loop guard (max 8 tool calls per turn)
+7. Rate limit (max 60 calls per minute)
+8. Audit logging for `shell_exec`
+
+See [`docs/shell-exec-safety.md`](../../docs/shell-exec-safety.md) for full details.
 
 ## License
 

package/dist/commands/completion.d.ts

@@ -0,0 +1,2 @@
+export declare function runCompletion(shell: string): Promise<void>;
+//# sourceMappingURL=completion.d.ts.map

package/dist/commands/completion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion.d.ts","sourceRoot":"","sources":["../../src/commands/completion.ts"],"names":[],"mappings":"AA2QA,wBAAsB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA4BhE"}

package/dist/commands/completion.js

@@ -0,0 +1,287 @@
+// ============================================================
+// Command: nexagent completion — generate shell completion scripts
+// Supports: bash, zsh, fish, powershell
+// ============================================================
+import chalk from 'chalk';
+const BASH_COMPLETION = `# NexAgent CLI bash completion
+# Source this file: eval "$(nexagent completion bash)"
+# Or install to: /etc/bash_completion.d/ or ~/.bash_completion
+
+_nexagent_completion() {
+    local cur prev opts
+    COMPREPLY=()
+    cur="\${COMP_WORDS[COMP_CWORD]}"
+    prev="\${COMP_WORDS[COMP_CWORD-1]}"
+
+    local commands="chat run memory session agent config models update changelog doctor server dashboard mcp completion"
+    local chat_opts="--agent --model --provider --memory --subagents --safety --max-turns --cwd --resume --json --debug --data-dir --no-color"
+    local run_opts="--agent --model --max-turns --cwd --dry-run --json --debug --data-dir --no-color"
+    local global_opts="--help --version --no-color --json --debug --data-dir"
+
+    if [[ \${cur} == -* ]]; then
+        COMPREPLY=( $(compgen -W "\${global_opts}" -- \${cur}) )
+        return 0
+    fi
+
+    if [[ \${COMP_CWORD} -eq 1 ]]; then
+        COMPREPLY=( $(compgen -W "\${commands}" -- \${cur}) )
+        return 0
+    fi
+
+    case "\${prev}" in
+        chat)
+            COMPREPLY=( $(compgen -W "\${chat_opts}" -- \${cur}) )
+            return 0
+            ;;
+        run)
+            COMPREPLY=( $(compgen -W "\${run_opts}" -- \${cur}) )
+            return 0
+            ;;
+        --provider)
+            COMPREPLY=( $(compgen -W "openai anthropic google ollama proxy kimi" -- \${cur}) )
+            return 0
+            ;;
+        --safety)
+            COMPREPLY=( $(compgen -W "strict standard permissive" -- \${cur}) )
+            return 0
+            ;;
+        --model)
+            COMPREPLY=( $(compgen -W "gpt-4o gpt-4o-mini gpt-4.1 claude-3-5-sonnet claude-3-7-sonnet gemini-1.5-pro" -- \${cur}) )
+            return 0
+            ;;
+    esac
+}
+
+complete -F _nexagent_completion nexagent
+`;
+const ZSH_COMPLETION = `#compdef nexagent
+# NexAgent CLI zsh completion
+# Install: copy to a directory in $fpath (e.g., /usr/local/share/zsh/site-functions/)
+
+_nexagent() {
+    local curcontext="$curcontext" state line
+    typeset -A opt_args
+
+    local -a commands
+    commands=(
+        'chat:Start an interactive chat session'
+        'run:Run a single prompt non-interactively'
+        'memory:Manage agent memory blocks'
+        'session:Manage chat sessions'
+        'agent:Manage agents'
+        'config:Manage configuration'
+        'models:List available models'
+        'update:Update to latest version'
+        'changelog:Show release notes'
+        'doctor:Diagnose installation health'
+        'server:Manage proxy gateway'
+        'dashboard:Start web dashboard'
+        'mcp:Manage MCP tools'
+        'completion:Generate shell completion'
+    )
+
+    _arguments -C \\
+        '(-h --help)'{-h,--help}'[Show help]' \\
+        '(-v --version)'{-v,--version}'[Show version]' \\
+        '--no-color[Disable colour output]' \\
+        '--json[Output machine-readable JSON]' \\
+        '--debug[Enable verbose debug logging]' \\
+        '--data-dir[Override agent data directory]:directory:_directories' \\
+        '1: :->command' \\
+        '*: :->args'
+
+    case "$state" in
+        command)
+            _describe -t commands 'nexagent commands' commands
+            ;;
+        args)
+            case "$line[1]" in
+                chat)
+                    _arguments \\
+                        '(-a --agent)'{-a,--agent}'[Agent name]:agent:' \\
+                        '(-m --model)'{-m,--model}'[Model override]:model:' \\
+                        '(-p --provider)'{-p,--provider}'[Provider]:provider:(openai anthropic google ollama proxy kimi)' \\
+                        '--safety[Safety level]:level:(strict standard permissive)' \\
+                        '--max-turns[Max turns]:number:' \\
+                        '--cwd[Working directory]:directory:_directories' \\
+                        '--resume[Resume session]:session:' \\
+                        '--no-memory[Disable memory]' \\
+                        '--no-subagents[Disable subagents]'
+                    ;;
+                run)
+                    _arguments \\
+                        '(-a --agent)'{-a,--agent}'[Agent name]:agent:' \\
+                        '(-m --model)'{-m,--model}'[Model override]:model:' \\
+                        '--max-turns[Max turns]:number:' \\
+                        '--cwd[Working directory]:directory:_directories' \\
+                        '--dry-run[Show what tools would do]' \\
+                        '--json[Output as JSON]'
+                    ;;
+            esac
+            ;;
+    esac
+}
+
+compdef _nexagent nexagent
+`;
+const FISH_COMPLETION = `# NexAgent CLI fish completion
+# Install: copy to ~/.config/fish/completions/nexagent.fish
+
+complete -c nexagent -f
+
+# Global options
+complete -c nexagent -s h -l help -d "Show help"
+complete -c nexagent -s v -l version -d "Show version"
+complete -c nexagent -l no-color -d "Disable colour output"
+complete -c nexagent -l json -d "Output machine-readable JSON"
+complete -c nexagent -l debug -d "Enable verbose debug logging"
+complete -c nexagent -l data-dir -d "Override agent data directory"
+
+# Commands
+complete -c nexagent -n "not __fish_seen_subcommand_from $commands" -a "chat" -d "Start an interactive chat session"
+complete -c nexagent -n "not __fish_seen_subcommand_from $commands" -a "run" -d "Run a single prompt non-interactively"
+complete -c nexagent -n "not __fish_seen_subcommand_from $commands" -a "memory" -d "Manage agent memory blocks"
+complete -c nexagent -n "not __fish_seen_subcommand_from $commands" -a "session" -d "Manage chat sessions"
+complete -c nexagent -n "not __fish_seen_subcommand_from $commands" -a "agent" -d "Manage agents"
+complete -c nexagent -n "not __fish_seen_subcommand_from $commands" -a "config" -d "Manage configuration"
+complete -c nexagent -n "not __fish_seen_subcommand_from $commands" -a "models" -d "List available models"
+complete -c nexagent -n "not __fish_seen_subcommand_from $commands" -a "update" -d "Update to latest version"
+complete -c nexagent -n "not __fish_seen_subcommand_from $commands" -a "changelog" -d "Show release notes"
+complete -c nexagent -n "not __fish_seen_subcommand_from $commands" -a "doctor" -d "Diagnose installation health"
+complete -c nexagent -n "not __fish_seen_subcommand_from $commands" -a "server" -d "Manage proxy gateway"
+complete -c nexagent -n "not __fish_seen_subcommand_from $commands" -a "dashboard" -d "Start web dashboard"
+complete -c nexagent -n "not __fish_seen_subcommand_from $commands" -a "mcp" -d "Manage MCP tools"
+complete -c nexagent -n "not __fish_seen_subcommand_from $commands" -a "completion" -d "Generate shell completion"
+
+# Chat options
+complete -c nexagent -n "__fish_seen_subcommand_from chat" -s a -l agent -d "Agent name"
+complete -c nexagent -n "__fish_seen_subcommand_from chat" -s m -l model -d "Model override"
+complete -c nexagent -n "__fish_seen_subcommand_from chat" -s p -l provider -d "Provider" -a "openai anthropic google ollama proxy kimi"
+complete -c nexagent -n "__fish_seen_subcommand_from chat" -l safety -d "Safety level" -a "strict standard permissive"
+complete -c nexagent -n "__fish_seen_subcommand_from chat" -l max-turns -d "Max turns"
+complete -c nexagent -n "__fish_seen_subcommand_from chat" -l cwd -d "Working directory"
+
+# Run options
+complete -c nexagent -n "__fish_seen_subcommand_from run" -s a -l agent -d "Agent name"
+complete -c nexagent -n "__fish_seen_subcommand_from run" -s m -l model -d "Model override"
+complete -c nexagent -n "__fish_seen_subcommand_from run" -l max-turns -d "Max turns"
+complete -c nexagent -n "__fish_seen_subcommand_from run" -l dry-run -d "Show what tools would do"
+`;
+const PWSH_COMPLETION = `# NexAgent CLI PowerShell completion
+# Install: Add this to your $PROFILE
+#   nexagent completion powershell | Out-String | Invoke-Expression
+# Or save to a file and dot-source it.
+
+Register-ArgumentCompleter -Native -CommandName nexagent -ScriptBlock {
+    param($wordToComplete, $commandAst, $cursorPosition)
+
+    $commands = @('chat','run','memory','session','agent','config','models','update','changelog','doctor','server','dashboard','mcp','completion')
+    $globalOpts = @('--help','--version','--no-color','--json','--debug','--data-dir')
+    $providers = @('openai','anthropic','google','ollama','proxy','kimi')
+    $safetyLevels = @('strict','standard','permissive')
+
+    $tokens = $commandAst.CommandElements | ForEach-Object { $_.ToString() }
+    $cmd = $tokens[1]
+
+    # Complete first-level command
+    if ($tokens.Count -eq 1 -or ($tokens.Count -eq 2 -and $wordToComplete -notmatch '^-')) {
+        $commands | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
+            [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
+        }
+        return
+    }
+
+    # Complete global flags
+    if ($wordToComplete -match '^-') {
+        $globalOpts | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
+            [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
+        }
+        return
+    }
+
+    # Sub-command specific completions
+    switch ($cmd) {
+        'chat' {
+            @('--agent','--model','--provider','--safety','--max-turns','--cwd','--resume','--no-memory','--no-subagents') |
+                Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
+                    [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
+                }
+        }
+        'run' {
+            @('--agent','--model','--max-turns','--cwd','--dry-run','--json') |
+                Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
+                    [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
+                }
+        }
+        'config' {
+            @('show','set','api-key') |
+                Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
+                    [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
+                }
+        }
+        'server' {
+            @('start','stop','status') |
+                Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
+                    [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
+                }
+        }
+        'memory' {
+            @('list','show','edit','delete','export','import') |
+                Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
+                    [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
+                }
+        }
+        'session' {
+            @('list','show','delete','export','import') |
+                Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
+                    [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
+                }
+        }
+        'agent' {
+            @('list','create','delete') |
+                Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
+                    [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
+                }
+        }
+        'mcp' {
+            @('list','search','install','uninstall','installed','run') |
+                Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
+                    [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
+                }
+        }
+    }
+}
+`;
+const SHELL_SCRIPTS = {
+    bash: BASH_COMPLETION,
+    zsh: ZSH_COMPLETION,
+    fish: FISH_COMPLETION,
+    powershell: PWSH_COMPLETION,
+};
+export async function runCompletion(shell) {
+    const normalized = shell.toLowerCase().trim();
+    if (normalized === 'install') {
+        console.log(chalk.bold('\n  Shell Completion Installation\n'));
+        console.log('  Bash:');
+        console.log('    eval "$(nexagent completion bash)"');
+        console.log('    # Or permanently: nexagent completion bash > ~/.bash_completion\n');
+        console.log('  Zsh:');
+        console.log('    eval "$(nexagent completion zsh)"');
+        console.log('    # Or permanently: nexagent completion zsh > /usr/local/share/zsh/site-functions/_nexagent\n');
+        console.log('  Fish:');
+        console.log('    nexagent completion fish > ~/.config/fish/completions/nexagent.fish\n');
+        console.log('  PowerShell:');
+        console.log('    nexagent completion powershell | Out-String | Invoke-Expression');
+        console.log('    # Or add to $PROFILE\n');
+        return;
+    }
+    const script = SHELL_SCRIPTS[normalized];
+    if (!script) {
+        console.error(chalk.red(`\n  Unknown shell: "\${shell}"`));
+        console.error(chalk.dim('  Supported shells: bash, zsh, fish, powershell'));
+        console.error(chalk.dim('  Run "nexagent completion install" for setup instructions.\n'));
+        process.exit(1);
+    }
+    console.log(script);
+}
+//# sourceMappingURL=completion.js.map

package/dist/commands/completion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion.js","sourceRoot":"","sources":["../../src/commands/completion.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,mEAAmE;AACnE,wCAAwC;AACxC,+DAA+D;AAE/D,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkDvB,CAAC;AAEF,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqEtB,CAAC;AAEF,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0CvB,CAAC;AAEF,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoFvB,CAAC;AAEF,MAAM,aAAa,GAA2B;IAC5C,IAAI,EAAE,eAAe;IACrB,GAAG,EAAE,cAAc;IACnB,IAAI,EAAE,eAAe;IACrB,UAAU,EAAE,eAAe;CAC5B,CAAC;AAEF,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,KAAa;IAC/C,MAAM,UAAU,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC;IAE9C,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,qCAAqC,CAAC,CAAC,CAAC;QAC/D,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACvB,OAAO,CAAC,GAAG,CAAC,wCAAwC,CAAC,CAAC;QACtD,OAAO,CAAC,GAAG,CAAC,uEAAuE,CAAC,CAAC;QACrF,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACtB,OAAO,CAAC,GAAG,CAAC,uCAAuC,CAAC,CAAC;QACrD,OAAO,CAAC,GAAG,CAAC,iGAAiG,CAAC,CAAC;QAC/G,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACvB,OAAO,CAAC,GAAG,CAAC,2EAA2E,CAAC,CAAC;QACzF,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;QAC7B,OAAO,CAAC,GAAG,CAAC,qEAAqE,CAAC,CAAC;QACnF,OAAO,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAC;QAC1C,OAAO;IACT,CAAC;IAED,MAAM,MAAM,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC;IACzC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,gCAAgC,CAAC,CAAC,CAAC;QAC3D,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,iDAAiD,CAAC,CAAC,CAAC;QAC5E,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,+DAA+D,CAAC,CAAC,CAAC;QAC1F,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AACtB,CAAC"}

package/dist/commands/dashboard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dashboard.d.ts","sourceRoot":"","sources":["../../src/commands/dashboard.ts"],"names":[],"mappings":"AAcA,UAAU,gBAAgB;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAID,wBAAsB,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwRxE"}
+{"version":3,"file":"dashboard.d.ts","sourceRoot":"","sources":["../../src/commands/dashboard.ts"],"names":[],"mappings":"AAiBA,UAAU,gBAAgB;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAID,wBAAsB,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgexE"}