@neocode-ai/web 1.1.1

package/src/content/docs/cli.mdx

@@ -0,0 +1,597 @@
+---
+title: CLI
+description: NeoCode CLI options and commands.
+---
+
+import { Tabs, TabItem } from "@astrojs/starlight/components"
+
+The NeoCode CLI by default starts the [TUI](/docs/tui) when run without any arguments.
+
+```bash
+neocode
+```
+
+But it also accepts commands as documented on this page. This allows you to interact with NeoCode programmatically.
+
+```bash
+neocode run "Explain how closures work in JavaScript"
+```
+
+---
+
+### tui
+
+Start the NeoCode terminal user interface.
+
+```bash
+neocode [project]
+```
+
+#### Flags
+
+| Flag         | Short | Description                                |
+| ------------ | ----- | ------------------------------------------ |
+| `--continue` | `-c`  | Continue the last session                  |
+| `--session`  | `-s`  | Session ID to continue                     |
+| `--prompt`   |       | Prompt to use                              |
+| `--model`    | `-m`  | Model to use in the form of provider/model |
+| `--agent`    |       | Agent to use                               |
+| `--port`     |       | Port to listen on                          |
+| `--hostname` |       | Hostname to listen on                      |
+
+---
+
+## Commands
+
+The NeoCode CLI also has the following commands.
+
+---
+
+### agent
+
+Manage agents for NeoCode.
+
+```bash
+neocode agent [command]
+```
+
+---
+
+### attach
+
+Attach a terminal to an already running NeoCode backend server started via `serve` or `web` commands.
+
+```bash
+neocode attach [url]
+```
+
+This allows using the TUI with a remote NeoCode backend. For example:
+
+```bash
+# Start the backend server for web/mobile access
+neocode web --port 4096 --hostname 0.0.0.0
+
+# In another terminal, attach the TUI to the running backend
+neocode attach http://10.20.30.40:4096
+```
+
+#### Flags
+
+| Flag        | Short | Description                       |
+| ----------- | ----- | --------------------------------- |
+| `--dir`     |       | Working directory to start TUI in |
+| `--session` | `-s`  | Session ID to continue            |
+
+---
+
+#### create
+
+Create a new agent with custom configuration.
+
+```bash
+neocode agent create
+```
+
+This command will guide you through creating a new agent with a custom system prompt and tool configuration.
+
+---
+
+#### list
+
+List all available agents.
+
+```bash
+neocode agent list
+```
+
+---
+
+### auth
+
+Command to manage credentials and login for providers.
+
+```bash
+neocode auth [command]
+```
+
+---
+
+#### login
+
+NeoCode is powered by the provider list at [Models.dev](https://models.dev), so you can use `neocode auth login` to configure API keys for any provider you'd like to use. This is stored in `~/.local/share/neocode/auth.json`.
+
+```bash
+neocode auth login
+```
+
+When NeoCode starts up it loads the providers from the credentials file. And if there are any keys defined in your environments or a `.env` file in your project.
+
+---
+
+#### list
+
+Lists all the authenticated providers as stored in the credentials file.
+
+```bash
+neocode auth list
+```
+
+Or the short version.
+
+```bash
+neocode auth ls
+```
+
+---
+
+#### logout
+
+Logs you out of a provider by clearing it from the credentials file.
+
+```bash
+neocode auth logout
+```
+
+---
+
+### github
+
+Manage the GitHub agent for repository automation.
+
+```bash
+neocode github [command]
+```
+
+---
+
+#### install
+
+Install the GitHub agent in your repository.
+
+```bash
+neocode github install
+```
+
+This sets up the necessary GitHub Actions workflow and guides you through the configuration process. [Learn more](/docs/github).
+
+---
+
+#### run
+
+Run the GitHub agent. This is typically used in GitHub Actions.
+
+```bash
+neocode github run
+```
+
+##### Flags
+
+| Flag      | Description                            |
+| --------- | -------------------------------------- |
+| `--event` | GitHub mock event to run the agent for |
+| `--token` | GitHub personal access token           |
+
+---
+
+### mcp
+
+Manage Model Context Protocol servers.
+
+```bash
+neocode mcp [command]
+```
+
+---
+
+#### add
+
+Add an MCP server to your configuration.
+
+```bash
+neocode mcp add
+```
+
+This command will guide you through adding either a local or remote MCP server.
+
+---
+
+#### list
+
+List all configured MCP servers and their connection status.
+
+```bash
+neocode mcp list
+```
+
+Or use the short version.
+
+```bash
+neocode mcp ls
+```
+
+---
+
+#### auth
+
+Authenticate with an OAuth-enabled MCP server.
+
+```bash
+neocode mcp auth [name]
+```
+
+If you don't provide a server name, you'll be prompted to select from available OAuth-capable servers.
+
+You can also list OAuth-capable servers and their authentication status.
+
+```bash
+neocode mcp auth list
+```
+
+Or use the short version.
+
+```bash
+neocode mcp auth ls
+```
+
+---
+
+#### logout
+
+Remove OAuth credentials for an MCP server.
+
+```bash
+neocode mcp logout [name]
+```
+
+---
+
+#### debug
+
+Debug OAuth connection issues for an MCP server.
+
+```bash
+neocode mcp debug <name>
+```
+
+---
+
+### models
+
+List all available models from configured providers.
+
+```bash
+neocode models [provider]
+```
+
+This command displays all models available across your configured providers in the format `provider/model`.
+
+This is useful for figuring out the exact model name to use in [your config](/docs/config/).
+
+You can optionally pass a provider ID to filter models by that provider.
+
+```bash
+neocode models anthropic
+```
+
+#### Flags
+
+| Flag        | Description                                                  |
+| ----------- | ------------------------------------------------------------ |
+| `--refresh` | Refresh the models cache from models.dev                     |
+| `--verbose` | Use more verbose model output (includes metadata like costs) |
+
+Use the `--refresh` flag to update the cached model list. This is useful when new models have been added to a provider and you want to see them in NeoCode.
+
+```bash
+neocode models --refresh
+```
+
+---
+
+### run
+
+Run neocode in non-interactive mode by passing a prompt directly.
+
+```bash
+neocode run [message..]
+```
+
+This is useful for scripting, automation, or when you want a quick answer without launching the full TUI. For example.
+
+```bash "neocode run"
+neocode run Explain the use of context in Go
+```
+
+You can also attach to a running `neocode serve` instance to avoid MCP server cold boot times on every run:
+
+```bash
+# Start a headless server in one terminal
+neocode serve
+
+# In another terminal, run commands that attach to it
+neocode run --attach http://localhost:4096 "Explain async/await in JavaScript"
+```
+
+#### Flags
+
+| Flag         | Short | Description                                                        |
+| ------------ | ----- | ------------------------------------------------------------------ |
+| `--command`  |       | The command to run, use message for args                           |
+| `--continue` | `-c`  | Continue the last session                                          |
+| `--session`  | `-s`  | Session ID to continue                                             |
+| `--share`    |       | Share the session                                                  |
+| `--model`    | `-m`  | Model to use in the form of provider/model                         |
+| `--agent`    |       | Agent to use                                                       |
+| `--file`     | `-f`  | File(s) to attach to message                                       |
+| `--format`   |       | Format: default (formatted) or json (raw JSON events)              |
+| `--title`    |       | Title for the session (uses truncated prompt if no value provided) |
+| `--attach`   |       | Attach to a running neocode server (e.g., http://localhost:4096)   |
+| `--port`     |       | Port for the local server (defaults to random port)                |
+
+---
+
+### serve
+
+Start a headless NeoCode server for API access. Check out the [server docs](/docs/server) for the full HTTP interface.
+
+```bash
+neocode serve
+```
+
+This starts an HTTP server that provides API access to neocode functionality without the TUI interface. Set `NEOCODE_SERVER_PASSWORD` to enable HTTP basic auth (username defaults to `neocode`).
+
+#### Flags
+
+| Flag         | Description                                |
+| ------------ | ------------------------------------------ |
+| `--port`     | Port to listen on                          |
+| `--hostname` | Hostname to listen on                      |
+| `--mdns`     | Enable mDNS discovery                      |
+| `--cors`     | Additional browser origin(s) to allow CORS |
+
+---
+
+### session
+
+Manage NeoCode sessions.
+
+```bash
+neocode session [command]
+```
+
+---
+
+#### list
+
+List all NeoCode sessions.
+
+```bash
+neocode session list
+```
+
+##### Flags
+
+| Flag          | Short | Description                          |
+| ------------- | ----- | ------------------------------------ |
+| `--max-count` | `-n`  | Limit to N most recent sessions      |
+| `--format`    |       | Output format: table or json (table) |
+
+---
+
+### stats
+
+Show token usage and cost statistics for your NeoCode sessions.
+
+```bash
+neocode stats
+```
+
+#### Flags
+
+| Flag        | Description                                                                 |
+| ----------- | --------------------------------------------------------------------------- |
+| `--days`    | Show stats for the last N days (all time)                                   |
+| `--tools`   | Number of tools to show (all)                                               |
+| `--models`  | Show model usage breakdown (hidden by default). Pass a number to show top N |
+| `--project` | Filter by project (all projects, empty string: current project)             |
+
+---
+
+### export
+
+Export session data as JSON.
+
+```bash
+neocode export [sessionID]
+```
+
+If you don't provide a session ID, you'll be prompted to select from available sessions.
+
+---
+
+### import
+
+Import session data from a JSON file or NeoCode share URL.
+
+```bash
+neocode import <file>
+```
+
+You can import from a local file or an NeoCode share URL.
+
+```bash
+neocode import session.json
+neocode import https://opncd.ai/s/abc123
+```
+
+---
+
+### web
+
+Start a headless NeoCode server with a web interface.
+
+```bash
+neocode web
+```
+
+This starts an HTTP server and opens a web browser to access NeoCode through a web interface. Set `NEOCODE_SERVER_PASSWORD` to enable HTTP basic auth (username defaults to `neocode`).
+
+#### Flags
+
+| Flag         | Description                                |
+| ------------ | ------------------------------------------ |
+| `--port`     | Port to listen on                          |
+| `--hostname` | Hostname to listen on                      |
+| `--mdns`     | Enable mDNS discovery                      |
+| `--cors`     | Additional browser origin(s) to allow CORS |
+
+---
+
+### acp
+
+Start an ACP (Agent Client Protocol) server.
+
+```bash
+neocode acp
+```
+
+This command starts an ACP server that communicates via stdin/stdout using nd-JSON.
+
+#### Flags
+
+| Flag         | Description           |
+| ------------ | --------------------- |
+| `--cwd`      | Working directory     |
+| `--port`     | Port to listen on     |
+| `--hostname` | Hostname to listen on |
+
+---
+
+### uninstall
+
+Uninstall NeoCode and remove all related files.
+
+```bash
+neocode uninstall
+```
+
+#### Flags
+
+| Flag            | Short | Description                                 |
+| --------------- | ----- | ------------------------------------------- |
+| `--keep-config` | `-c`  | Keep configuration files                    |
+| `--keep-data`   | `-d`  | Keep session data and snapshots             |
+| `--dry-run`     |       | Show what would be removed without removing |
+| `--force`       | `-f`  | Skip confirmation prompts                   |
+
+---
+
+### upgrade
+
+Updates neocode to the latest version or a specific version.
+
+```bash
+neocode upgrade [target]
+```
+
+To upgrade to the latest version.
+
+```bash
+neocode upgrade
+```
+
+To upgrade to a specific version.
+
+```bash
+neocode upgrade v0.1.48
+```
+
+#### Flags
+
+| Flag       | Short | Description                                                       |
+| ---------- | ----- | ----------------------------------------------------------------- |
+| `--method` | `-m`  | The installation method that was used; curl, npm, pnpm, bun, brew |
+
+---
+
+## Global Flags
+
+The neocode CLI takes the following global flags.
+
+| Flag           | Short | Description                          |
+| -------------- | ----- | ------------------------------------ |
+| `--help`       | `-h`  | Display help                         |
+| `--version`    | `-v`  | Print version number                 |
+| `--print-logs` |       | Print logs to stderr                 |
+| `--log-level`  |       | Log level (DEBUG, INFO, WARN, ERROR) |
+
+---
+
+## Environment variables
+
+NeoCode can be configured using environment variables.
+
+| Variable                             | Type    | Description                                      |
+| ------------------------------------ | ------- | ------------------------------------------------ |
+| `NEOCODE_AUTO_SHARE`                 | boolean | Automatically share sessions                     |
+| `NEOCODE_GIT_BASH_PATH`              | string  | Path to Git Bash executable on Windows           |
+| `NEOCODE_CONFIG`                     | string  | Path to config file                              |
+| `NEOCODE_CONFIG_DIR`                 | string  | Path to config directory                         |
+| `NEOCODE_CONFIG_CONTENT`             | string  | Inline json config content                       |
+| `NEOCODE_DISABLE_AUTOUPDATE`         | boolean | Disable automatic update checks                  |
+| `NEOCODE_DISABLE_PRUNE`              | boolean | Disable pruning of old data                      |
+| `NEOCODE_DISABLE_TERMINAL_TITLE`     | boolean | Disable automatic terminal title updates         |
+| `NEOCODE_PERMISSION`                 | string  | Inlined json permissions config                  |
+| `NEOCODE_DISABLE_DEFAULT_PLUGINS`    | boolean | Disable default plugins                          |
+| `NEOCODE_DISABLE_LSP_DOWNLOAD`       | boolean | Disable automatic LSP server downloads           |
+| `NEOCODE_ENABLE_EXPERIMENTAL_MODELS` | boolean | Enable experimental models                       |
+| `NEOCODE_DISABLE_AUTOCOMPACT`        | boolean | Disable automatic context compaction             |
+| `NEOCODE_DISABLE_CLAUDE_CODE`        | boolean | Disable reading from `.claude` (prompt + skills) |
+| `NEOCODE_DISABLE_CLAUDE_CODE_PROMPT` | boolean | Disable reading `~/.claude/CLAUDE.md`            |
+| `NEOCODE_DISABLE_CLAUDE_CODE_SKILLS` | boolean | Disable loading `.claude/skills`                 |
+| `NEOCODE_CLIENT`                     | string  | Client identifier (defaults to `cli`)            |
+| `NEOCODE_ENABLE_EXA`                 | boolean | Enable Exa web search tools                      |
+| `NEOCODE_SERVER_PASSWORD`            | string  | Enable basic auth for `serve`/`web`              |
+| `NEOCODE_SERVER_USERNAME`            | string  | Override basic auth username (default `neocode`) |
+
+---
+
+### Experimental
+
+These environment variables enable experimental features that may change or be removed.
+
+| Variable                                       | Type    | Description                             |
+| ---------------------------------------------- | ------- | --------------------------------------- |
+| `NEOCODE_EXPERIMENTAL`                         | boolean | Enable all experimental features        |
+| `NEOCODE_EXPERIMENTAL_ICON_DISCOVERY`          | boolean | Enable icon discovery                   |
+| `NEOCODE_EXPERIMENTAL_DISABLE_COPY_ON_SELECT`  | boolean | Disable copy on select in TUI           |
+| `NEOCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS` | number  | Default timeout for bash commands in ms |
+| `NEOCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX`        | number  | Max output tokens for LLM responses     |
+| `NEOCODE_EXPERIMENTAL_FILEWATCHER`             | boolean | Enable file watcher for entire dir      |
+| `NEOCODE_EXPERIMENTAL_OXFMT`                   | boolean | Enable oxfmt formatter                  |
+| `NEOCODE_EXPERIMENTAL_LSP_TOOL`                | boolean | Enable experimental LSP tool            |
+| `NEOCODE_EXPERIMENTAL_DISABLE_FILEWATCHER`     | boolean | Disable file watcher                    |
+| `NEOCODE_EXPERIMENTAL_EXA`                     | boolean | Enable experimental Exa features        |
+| `NEOCODE_EXPERIMENTAL_LSP_TY`                  | boolean | Enable experimental LSP type checking   |
+| `NEOCODE_EXPERIMENTAL_MARKDOWN`                | boolean | Enable experimental markdown features   |
+| `NEOCODE_EXPERIMENTAL_PLAN_MODE`               | boolean | Enable plan mode                        |