io.github.easy4j.opencode.cli

Class OpenCodeCli

java.lang.Object

io.github.easy4j.opencode.cli.OpenCodeCli

public class OpenCodeCli
extends Object

Facade for the local opencode CLI commands.

Wraps an OpenCodeCliExecutor and provides typed methods for each CLI sub-command (session, agent, models, providers, mcp, etc.).

Since:

1.0.0

Author:

Loong Wan

See Also:

OpenCodeCliExecutor, OpenCodeCliResult, opencode CLI docs

Constructor Summary

Constructors

Constructor and Description
OpenCodeCli(OpenCodeCliExecutor executor) 创建 open code cli 实例，并按传入依赖确定资源所有权。

Method Summary

Modifier and Type	Method and Description
OpenCodeCliResult	acp(String cwd) opencode acp [--cwd ...]
OpenCodeCliResult	agentCreate(String path, String description, String mode, String permissions, String model) {@code opencode agent create --path ...
OpenCodeCliResult	agentList() opencode agent list
OpenCodeCliResult	attach(String url, String dir, String sessionId, String username, String password) {@code opencode attach [--dir ...
OpenCodeCliResult	authList() opencode auth list（与 providers list 等价）
OpenCodeCliResult	authLogin(String provider, String method) {@code opencode auth login [--provider ...
OpenCodeCliResult	authLogout(String provider) opencode auth logout [provider]
OpenCodeCliResult	consoleLogin(String url) opencode console login [url]
OpenCodeCliResult	consoleLogout(String email) opencode console logout [email]
OpenCodeCliResult	consoleOpen() opencode console open
OpenCodeCliResult	consoleOrgs() opencode console orgs
OpenCodeCliResult	consoleSwitch() opencode console switch
OpenCodeCliResult	db(String query, String format) opencode db [query] [--format json|tsv]
OpenCodeCliResult	dbPath() opencode db path
OpenCodeCliResult	debugConfig() opencode debug config
OpenCodeCliResult	debugInfo() opencode debug info
OpenCodeCliResult	debugPaths() opencode debug paths
OpenCodeCliResult	debugScrap() opencode debug scrap
OpenCodeCliResult	debugSkill() opencode debug skill
OpenCodeCliResult	debugStartup() opencode debug startup
OpenCodeCliExecutor	executor() 获取 CLI 执行器（用于自定义命令）。
OpenCodeCliResult	export(String sessionId, boolean sanitize) opencode export [sessionID] [--sanitize]
OpenCodeCliResult	generate() opencode generate 打印带 JS 代码示例注入的 OpenAPI spec。
OpenCodeCliResult	githubInstall() opencode github install
OpenCodeCliResult	githubRun(String event, String token) {@code opencode github run [--event ...
OpenCodeCliResult	help() opencode --help
OpenCodeCliResult	importSession(String fileOrUrl) opencode import <file>
OpenCodeCliResult	mcpAdd(String name, String url) opencode mcp add <name> ...
OpenCodeCliResult	mcpAddLocal(String name, String... localCmd) opencode mcp add <name> 后接本地命令（exec 形式）。
OpenCodeCliResult	mcpAuth(String name) opencode mcp auth [name]
OpenCodeCliResult	mcpDebug(String name) opencode mcp debug <name>
OpenCodeCliResult	mcpList() opencode mcp list
OpenCodeCliResult	mcpLogout(String name) opencode mcp logout [name]
OpenCodeCliResult	models() opencode models
OpenCodeCliResult	models(String provider, boolean verbose, boolean refresh) opencode models <provider> [--verbose] [--refresh]
OpenCodeCliResult	plugin(String module, boolean global, boolean force) opencode plugin <module> [--global] [--force]
OpenCodeCliResult	pr(int number) opencode pr <number>
OpenCodeCliResult	providersList() opencode providers list
OpenCodeCliResult	providersLogin(String provider, String method) {@code opencode providers login [--provider ...
OpenCodeCliResult	providersLogout(String provider) opencode providers logout [provider]
OpenCodeCliResult	run(String message) opencode run <message> 非交互模式执行 prompt，返回 AI 响应。
OpenCodeCliResult	run(String message, String model) opencode run --model <model> <message>
OpenCodeCliResult	run(String message, String agent, String model) opencode run --agent <agent> --model <model> <message>
OpenCodeCliResult	runJson(String message) opencode run --format json <message> 返回 JSON 格式的原始事件流。
OpenCodeCliResult	runJson(String message, String sessionId, String model) opencode run --format json --session <sessionId> --message <message>
OpenCodeCliResult	serve(Integer port, String hostname) opencode serve [--port N --hostname H]
OpenCodeCliResult	sessionDelete(String sessionId) opencode session delete <sessionId>
OpenCodeCliResult	sessionList() opencode session list --format json
OpenCodeCliResult	sessionList(int maxCount) opencode session list --max-count <n> --format json
OpenCodeCliResult	stats(Integer days, Integer tools, Integer models, String project) {@code opencode stats [--days ...
OpenCodeCliResult	uninstall(boolean keepConfig, boolean keepData, boolean dryRun, boolean force) opencode uninstall [--keep-config] [--keep-data] [--dry-run] [--force]
OpenCodeCliResult	upgrade() opencode upgrade
OpenCodeCliResult	upgrade(String target, String method) opencode upgrade <target> [--method ...]
OpenCodeCliResult	version() opencode --version
OpenCodeCliResult	web(Integer port, String hostname) opencode web [--port N --hostname H]

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

OpenCodeCli

public OpenCodeCli(OpenCodeCliExecutor executor)

创建 open code cli 实例，并按传入依赖确定资源所有权。

Parameters:

executor - 负责启动子进程并收集输出的 CLI 执行器

Method Detail

executor

public OpenCodeCliExecutor executor()

获取 CLI 执行器（用于自定义命令）。

Returns:

OpenCode SDK 返回的CLI 执行器对象

version

public OpenCodeCliResult version()

opencode --version

Returns:

CLI 的退出状态、标准输出和错误输出

help

public OpenCodeCliResult help()

opencode --help

Returns:

CLI 的退出状态、标准输出和错误输出

run

public OpenCodeCliResult run(String message)

opencode run <message>

非交互模式执行 prompt，返回 AI 响应。

Parameters:

message - 传递给 OpenCode CLI 的提示文本

Returns:

CLI 的退出状态、标准输出和错误输出

run

public OpenCodeCliResult run(String message,
                             String model)

opencode run --model <model> <message>

Parameters:

message - 传递给 OpenCode CLI 的提示文本

model - 模型标识，通常采用 provider/model 格式；为空时使用默认模型

Returns:

CLI 的退出状态、标准输出和错误输出

run

public OpenCodeCliResult run(String message,
                             String agent,
                             String model)

opencode run --agent <agent> --model <model> <message>

Parameters:

message - 传递给 OpenCode CLI 的提示文本

agent - 执行请求的智能体名称；为空时使用服务端默认智能体

model - 模型标识，通常采用 provider/model 格式；为空时使用默认模型

Returns:

CLI 的退出状态、标准输出和错误输出

runJson

public OpenCodeCliResult runJson(String message)

opencode run --format json <message>

返回 JSON 格式的原始事件流。

Parameters:

message - 传递给 OpenCode CLI 的提示文本

Returns:

CLI 的退出状态、标准输出和错误输出

runJson

public OpenCodeCliResult runJson(String message,
                                 String sessionId,
                                 String model)

opencode run --format json --session <sessionId> --message <message>

Parameters:

message - 传递给 OpenCode CLI 的提示文本

sessionId - OpenCode 会话 ID；不得为空

model - 模型标识，通常采用 provider/model 格式；为空时使用默认模型

Returns:

CLI 的退出状态、标准输出和错误输出

sessionList

public OpenCodeCliResult sessionList()

opencode session list --format json

Returns:

CLI 的退出状态、标准输出和错误输出

sessionList

public OpenCodeCliResult sessionList(int maxCount)

opencode session list --max-count <n> --format json

Parameters:

maxCount - 最大返回会话数量

Returns:

CLI 的退出状态、标准输出和错误输出

sessionDelete

public OpenCodeCliResult sessionDelete(String sessionId)

opencode session delete <sessionId>

Parameters:

sessionId - OpenCode 会话 ID；不得为空

Returns:

CLI 的退出状态、标准输出和错误输出

agentList

public OpenCodeCliResult agentList()

opencode agent list

Returns:

CLI 的退出状态、标准输出和错误输出

agentCreate

public OpenCodeCliResult agentCreate(String path,
                                     String description,
                                     String mode,
                                     String permissions,
                                     String model)

opencode agent create --path ... --description ... --mode ... --tools ...

Parameters:

path - 文件或工作目录路径

description - 资源的可读说明；为空时由 OpenCode 使用默认描述

mode - 智能体运行模式或 CLI 行为模式

permissions - 智能体创建时使用的权限配置文本

model - 模型标识，通常采用 provider/model 格式；为空时使用默认模型

Returns:

CLI 的退出状态、标准输出和错误输出

models

public OpenCodeCliResult models()

opencode models

Returns:

CLI 的退出状态、标准输出和错误输出

models

public OpenCodeCliResult models(String provider,
                                boolean verbose,
                                boolean refresh)

opencode models <provider> [--verbose] [--refresh]

Parameters:

provider - 模型提供方 ID；为空时不限制提供方

verbose - 是否输出模型的详细元数据

refresh - 是否在列出模型前强制刷新提供方元数据

Returns:

CLI 的退出状态、标准输出和错误输出

providersList

public OpenCodeCliResult providersList()

opencode providers list

Returns:

CLI 的退出状态、标准输出和错误输出

providersLogin

public OpenCodeCliResult providersLogin(String provider,
                                        String method)

opencode providers login [--provider ... --method ...]

Parameters:

provider - 模型提供方 ID；为空时不限制提供方

method - 认证或升级方式

Returns:

CLI 的退出状态、标准输出和错误输出

providersLogout

public OpenCodeCliResult providersLogout(String provider)

opencode providers logout [provider]

Parameters:

provider - 模型提供方 ID；为空时不限制提供方

Returns:

CLI 的退出状态、标准输出和错误输出

authList

public OpenCodeCliResult authList()

opencode auth list（与 providers list 等价）

Returns:

CLI 的退出状态、标准输出和错误输出

authLogin

public OpenCodeCliResult authLogin(String provider,
                                   String method)

opencode auth login [--provider ... --method ...]

Parameters:

provider - 模型提供方 ID；为空时不限制提供方

method - 认证或升级方式

Returns:

CLI 的退出状态、标准输出和错误输出

authLogout

public OpenCodeCliResult authLogout(String provider)

opencode auth logout [provider]

Parameters:

provider - 模型提供方 ID；为空时不限制提供方

Returns:

CLI 的退出状态、标准输出和错误输出

mcpList

public OpenCodeCliResult mcpList()

opencode mcp list

Returns:

CLI 的退出状态、标准输出和错误输出

mcpAdd

public OpenCodeCliResult mcpAdd(String name,
                                String url)

opencode mcp add <name> ... 远程 MCP server（url 形式）。

Parameters:

name - 资源名称

url - 远程服务或控制台 URL

Returns:

CLI 的退出状态、标准输出和错误输出

mcpAddLocal

public OpenCodeCliResult mcpAddLocal(String name,
                                     String... localCmd)

opencode mcp add <name> 后接本地命令（exec 形式）。

命令经 -- 透传给 opencode，例如 opencode mcp add foo -- npx server

Parameters:

name - 资源名称

localCmd - 追加到命令行的可变参数；每个元素作为独立参数传递

Returns:

CLI 的退出状态、标准输出和错误输出

mcpLogout

public OpenCodeCliResult mcpLogout(String name)

opencode mcp logout [name]

Parameters:

name - 资源名称

Returns:

CLI 的退出状态、标准输出和错误输出

mcpAuth

public OpenCodeCliResult mcpAuth(String name)

opencode mcp auth [name]

Parameters:

name - 资源名称

Returns:

CLI 的退出状态、标准输出和错误输出

mcpDebug

public OpenCodeCliResult mcpDebug(String name)

opencode mcp debug <name>

Parameters:

name - 资源名称

Returns:

CLI 的退出状态、标准输出和错误输出

upgrade

public OpenCodeCliResult upgrade()

opencode upgrade

Returns:

CLI 的退出状态、标准输出和错误输出

upgrade

public OpenCodeCliResult upgrade(String target,
                                 String method)

opencode upgrade <target> [--method ...]

Parameters:

target - 升级目标版本；为空时由 CLI 选择最新版本

method - 认证或升级方式

Returns:

CLI 的退出状态、标准输出和错误输出

uninstall

public OpenCodeCliResult uninstall(boolean keepConfig,
                                   boolean keepData,
                                   boolean dryRun,
                                   boolean force)

opencode uninstall [--keep-config] [--keep-data] [--dry-run] [--force]

Parameters:

keepConfig - 卸载时是否保留本地配置

keepData - 卸载时是否保留会话和缓存数据

dryRun - 是否仅预览操作而不实际修改本地安装

force - 是否强制执行操作

Returns:

CLI 的退出状态、标准输出和错误输出

stats

public OpenCodeCliResult stats(Integer days,
                               Integer tools,
                               Integer models,
                               String project)

opencode stats [--days ... --tools ... --models ... --project ...]

Parameters:

days - 统计覆盖的最近天数；为 null 时使用 CLI 默认范围

tools - 统计结果中最多展示的工具数量；为 null 时使用 CLI 默认值

models - 统计结果中最多展示的模型数量；为 null 时使用 CLI 默认值

project - 统计限定的项目名称；为空时统计全部项目

Returns:

CLI 的退出状态、标准输出和错误输出

export

public OpenCodeCliResult export(String sessionId,
                                boolean sanitize)

opencode export [sessionID] [--sanitize]

Parameters:

sessionId - OpenCode 会话 ID；不得为空

sanitize - 是否在导出结果中移除敏感信息

Returns:

CLI 的退出状态、标准输出和错误输出

importSession

public OpenCodeCliResult importSession(String fileOrUrl)

opencode import <file>

Parameters:

fileOrUrl - 待导入的本地文件路径或远程 URL

Returns:

CLI 的退出状态、标准输出和错误输出

db

public OpenCodeCliResult db(String query,
                            String format)

opencode db [query] [--format json|tsv]

Parameters:

query - 搜索或数据库查询表达式

format - 输出格式名称；为空时使用 CLI 默认格式

Returns:

CLI 的退出状态、标准输出和错误输出

dbPath

public OpenCodeCliResult dbPath()

opencode db path

Returns:

CLI 的退出状态、标准输出和错误输出

debugConfig

public OpenCodeCliResult debugConfig()

opencode debug config

Returns:

CLI 的退出状态、标准输出和错误输出

debugPaths

public OpenCodeCliResult debugPaths()

opencode debug paths

Returns:

CLI 的退出状态、标准输出和错误输出

debugInfo

public OpenCodeCliResult debugInfo()

opencode debug info

Returns:

CLI 的退出状态、标准输出和错误输出

debugScrap

public OpenCodeCliResult debugScrap()

opencode debug scrap

Returns:

CLI 的退出状态、标准输出和错误输出

debugSkill

public OpenCodeCliResult debugSkill()

opencode debug skill

Returns:

CLI 的退出状态、标准输出和错误输出

debugStartup

public OpenCodeCliResult debugStartup()

opencode debug startup

Returns:

CLI 的退出状态、标准输出和错误输出

serve

public OpenCodeCliResult serve(Integer port,
                               String hostname)

opencode serve [--port N --hostname H]

Parameters:

port - 监听端口；为 null 时使用 CLI 默认值

hostname - 监听地址；为空时使用 CLI 默认值

Returns:

CLI 的退出状态、标准输出和错误输出

web

public OpenCodeCliResult web(Integer port,
                             String hostname)

opencode web [--port N --hostname H]

Parameters:

port - 监听端口；为 null 时使用 CLI 默认值

hostname - 监听地址；为空时使用 CLI 默认值

Returns:

CLI 的退出状态、标准输出和错误输出

acp

public OpenCodeCliResult acp(String cwd)

opencode acp [--cwd ...]

Parameters:

cwd - CLI 进程使用的当前工作目录；为空时继承配置

Returns:

CLI 的退出状态、标准输出和错误输出

attach

public OpenCodeCliResult attach(String url,
                                String dir,
                                String sessionId,
                                String username,
                                String password)

opencode attach <url> [--dir ... --session ... --username ... --password ...]

Parameters:

url - 远程服务或控制台 URL

dir - CLI 命令作用目录；为空时使用配置工作目录

sessionId - OpenCode 会话 ID；不得为空

username - OpenCode Server Basic Auth 用户名

password - OpenCode Server Basic Auth 密码；日志中不得明文输出

Returns:

CLI 的退出状态、标准输出和错误输出

generate

public OpenCodeCliResult generate()

opencode generate

打印带 JS 代码示例注入的 OpenAPI spec。

Returns:

CLI 的退出状态、标准输出和错误输出

githubInstall

public OpenCodeCliResult githubInstall()

opencode github install

Returns:

CLI 的退出状态、标准输出和错误输出

githubRun

public OpenCodeCliResult githubRun(String event,
                                   String token)

opencode github run [--event ... --token ...]

Parameters:

event - 触发当前回调的完整 SSE 事件

token - GitHub 访问令牌；为空时由 CLI 自行解析

Returns:

CLI 的退出状态、标准输出和错误输出

pr

public OpenCodeCliResult pr(int number)

opencode pr <number>

Parameters:

number - GitHub Pull Request 编号

Returns:

CLI 的退出状态、标准输出和错误输出

plugin

public OpenCodeCliResult plugin(String module,
                                boolean global,
                                boolean force)

opencode plugin <module> [--global] [--force]

Parameters:

module - 插件模块名称或安装来源

global - 是否在全局作用域安装插件

force - 是否强制执行操作

Returns:

CLI 的退出状态、标准输出和错误输出

consoleLogin

public OpenCodeCliResult consoleLogin(String url)

opencode console login [url]

Parameters:

url - 远程服务或控制台 URL

Returns:

CLI 的退出状态、标准输出和错误输出

consoleLogout

public OpenCodeCliResult consoleLogout(String email)

opencode console logout [email]

Parameters:

email - 需要退出登录的控制台账号邮箱；为空时使用当前账号

Returns:

CLI 的退出状态、标准输出和错误输出

consoleOrgs

public OpenCodeCliResult consoleOrgs()

opencode console orgs

Returns:

CLI 的退出状态、标准输出和错误输出

consoleSwitch

public OpenCodeCliResult consoleSwitch()

opencode console switch

Returns:

CLI 的退出状态、标准输出和错误输出

consoleOpen

public OpenCodeCliResult consoleOpen()

opencode console open

Returns:

CLI 的退出状态、标准输出和错误输出