Skip to main content
Guides

Using the CLI

This article describes the run modes and core features of Qoder CN CLI, including TUI mode, Print mode, MCP services, permission control, worktrees, memory, subagents, and commands.

TUI mode

Run qoderclicn in any project root to enter the default TUI (interactive) mode. You can either chat with the CLI in natural language or use slash commands to trigger specific features.

Input modes

The TUI provides several input modes:
CommandDescription
>Chat mode (default). Enter any text to converse with the CLI.
!Bash mode. In chat mode, enter ! to run shell commands directly.
/Slash mode. In chat mode, enter / to open and run built-in commands.
\⏎Press Enter to start multiline input.

Built-in tools

Qoder CN CLI ships with built-in tools such as Grep, Read, Write, and Bash for file/directory operations and shell command execution.

Slash commands

The following built-in slash commands provide quick access to features and settings:
CommandDescription
/loginLog in to your Qoder CN account.
/helpShow TUI help.
/initInitialize or update the AGENTS.md memory file in the project.
/memoryOpen the memory overview to manage user-level, project-level, local memory, and auto-memory entries.
/questRun a spec-based delegated task.
/reviewReview local code changes.
/resumeView and resume sessions.
/clearClear the history context of the current session.
/compactSummarize the history context of the current session.
/usageShow the current credit usage.
/statusView CLI status, including version, model, account, API connectivity, and tool status.
/configView the Qoder CN CLI system configuration.
/effortAdjust the reasoning depth of the current model and related model parameters.
/agentsSubagent command: view, create, and manage subagents.
/tasksView background tasks that are currently running.
/release-notesShow the Qoder CN CLI release notes.
/vimOpen an external editor to edit input.
/feedbackSend feedback about Qoder CN CLI.
/quitExit the TUI.
/logoutLog out of your Qoder CN account.
For more information about built-in commands, command types, and custom commands, see the Commands section below.

Advanced startup options

When launching the CLI, use the following options to control its behavior:
OptionDescriptionExample
-wSpecify the workspace directory.qoderclicn -w /Users/demo/projects/nacos
-cContinue the last session.qoderclicn -c
-rResume a specific session.qoderclicn -r *******-c09a-40a9-82a7-a565413fa39
--allowed-toolsAllow only the specified tools.qoderclicn --allowed-tools=Read,Write
--disallowed-toolsDisallow the specified tools.qoderclicn --disallowed-tools=Read,Write
--max-turnsSet the maximum number of conversation turns.qoderclicn --max-turns=10
--yoloSkip permission checks.qoderclicn --yolo
For more startup parameters and configuration related to permissions, see the Permissions section below. Print mode is a non-interactive mode. Run qoderclicn --print to enter this mode. The output is printed in the format specified by --output-format.

Parameters

The following global parameters can be used with any command:
ParameterDescriptionExample
-pRun the agent non-interactively.qoderclicn -q -p hi
--output-formatOutput format: text, json, or stream-json.qoderclicn --output-format=json
-wSpecify the workspace directory.qoderclicn -w /Users/qoder_user/projects/qoder_demo
-cContinue the last session.qoderclicn -c
-rResume a specific session.qoderclicn -r ********-c09a-40a9-82a7-a565413fa393
--allowed-toolsAllow only the specified tools.qoderclicn --allowed-tools=Read,Write
--disallowed-toolsDisallow the specified tools.qoderclicn --disallowed-tools=Read,Write
--max-turnsSet the maximum number of conversation turns.qoderclicn --max-turns=10
--yoloSkip permission checks.qoderclicn --yolo

MCP services

Qoder CN CLI can connect to Model Context Protocol (MCP) services to use external tools and data sources. Once a service is added, its tools are available to the agent in both interactive and non-interactive sessions.

Quick start

Use qoderclicn mcp add to add a stdio MCP service. The command following -- is the service process that Qoder CN CLI needs to launch.
qoderclicn mcp add playwright -- npx -y @playwright/mcp@latest
Stdio services start automatically along with the CLI. If Qoder CN CLI is already running, use /mcp reload to rediscover MCP services and tools; new sessions perform discovery automatically at startup.

Service types

Use -t to choose the MCP transport type.
TypeUse case
stdioMCP service runs as a local command.
sseMCP service is exposed through a Server-Sent Events endpoint.
httpMCP service is exposed through an HTTP endpoint.
wsMCP service is exposed through a WebSocket endpoint.
If no type is specified, local command services use the default stdio behavior.

Scope

Use -s to choose where the MCP service configuration is saved.
ScopeUse case
userYou want the service to be available across all projects for the current account.
localYou want the service to be available only for the current project on this machine. This is the default scope.
projectYou want the service configuration to be shared with the project.
MCP service configurations are saved in the following files:
# User-level configuration
~/.qoder-cn/settings.json

# Local project-level configuration, typically not committed
${project}/.qoder/settings.local.json

# Project-level configuration, typically committed with the project
${project}/.mcp.json

Manage services

List configured services:
qoderclicn mcp list
Remove a service:
qoderclicn mcp remove playwright
Common MCP services include:
qoderclicn mcp add context7 -- npx -y @upstash/context7-mcp@latest
qoderclicn mcp add deepwiki -- npx -y mcp-deepwiki@latest
qoderclicn mcp add chrome-devtools -- npx chrome-devtools-mcp@latest

MCP permissions

MCP tools still go through the Qoder CN CLI permission system. In default mode, MCP tool calls typically require confirmation. You can approve a specific tool, approve all tools under a given MCP service, or configure rules in settings. MCP tool names typically use the following format:
mcp__<server>__<tool>
Example:
{
  "permissions": {
    "allow": [
      "mcp__context7__*"
    ],
    "deny": []
  }
}

Troubleshooting

If MCP tools are unavailable:
  • Run qoderclicn mcp list to confirm that the service is configured.
  • If Qoder CN CLI is already running, execute /mcp reload after adding or modifying a service.
  • Verify that the command following -- can run correctly in a terminal.
  • For npx-based services, confirm that Node.js and network access are available.
  • If a service is connected but tool calls are blocked, check the permission prompts.

Permissions

Qoder CN CLI provides fine-grained permission control over tool execution, covering file reads and writes, Bash commands, web fetching, MCP tools, subagents, and other built-in tools.

Permission modes

Permission modes determine how Qoder CN CLI handles tool calls. Each mode is positioned differently along the two dimensions of "automation level" and "safety leniency".
ModeUse caseBehavior
defaultRegular interactive use.Safe reads and internal actions run automatically; sensitive operations require confirmation.
accept_editsEveryday coding tasks.Safe file edits within the working directory are auto-approved; shell commands, external actions, and sensitive paths still go through normal checks.
autoAutomated runs and goal execution.No prompts. Safe reads and edits within the workspace are auto-approved; risky actions are denied or handed off to an AI classifier.
bypass_permissions (YOLO)For trusted local experiments only.Skips all approval prompts. All tool calls are automatically allowed.
dont_askHeadless workflows that must not prompt.Never asks. Any action that would normally require confirmation is denied.

Plan and Goal modes

Plan is an independent work state (not a permission policy) that coexists with any of the permission modes above. Toggle it with the /plan command. Once entered, Qoder CN CLI performs read-only code exploration and outputs a plan; writes are restricted to plan files. Goal is an autonomous execution state. Enter it with /goal set <goal> — this automatically switches to auto mode and locks the Shift+Tab toggle. Use /goal clear or /goal pause to exit. In an interactive session, press Shift+Tab to cycle through all permission modes; press Ctrl+Y to jump directly to YOLO mode.

Startup parameters

Use --permission-mode to select the default behavior for the current session:
qoderclicn --permission-mode default
qoderclicn --permission-mode accept_edits
qoderclicn --permission-mode plan           # Legacy compatibility; effectively translated to default + entering the Plan work state
qoderclicn --permission-mode auto
qoderclicn --permission-mode bypass_permissions
qoderclicn --permission-mode yolo           # Equivalent to bypass_permissions
qoderclicn --permission-mode dont_ask

# Shortcuts
qoderclicn --yolo                         # Equivalent to --permission-mode bypass_permissions
qoderclicn --dangerously-skip-permissions # Same as above
Multiple naming formats are supported (case-insensitive). Common aliases include accept_edits / acceptEdits, bypass_permissions / bypassPermissions / yolo, and dont_ask / dontAsk.
Non-default modes take effect only in trusted directories. If the current directory is not trusted, Qoder CN CLI falls back to default .

How permissions are decided

Qoder CN CLI performs a permission check before each tool call. There are only three possible results: allow (execute immediately), ask (external confirmation required), and deny (execution blocked). Decision order:
  1. Check deny rules first — if matched, deny.
  2. The tool's own safety checks (such as dangerous command detection and sensitive path detection).
  3. ask rules — if matched, mark as requiring confirmation.
  4. Tool-level allow rules and any automatic allow behavior implied by the mode.
  5. If the final result is still ask, the runtime environment decides how to consume it.
RuntimeFate of askDescription
TUI (interactive terminal)Confirmation prompt.The user chooses allow/deny in the terminal.
Headless (-p/--prompt)Auto-denied.Nobody is available to interact; ask becomes deny.
SDK (stdio protocol)Sends a canUseTool callback to the host.The host program decides allow/deny.
ACP (IDE integration)Sends a requestPermission RPC to the IDE.The IDE prompts or auto-decides.

Configuration sources and precedence

Rules are merged from multiple sources across 8 layers, from lowest to highest precedence:
LayerSourceDescription
1userSettings~/.qoder-cn/settings.json (user-global).
2projectSettings/.qoder/settings.json (project-level, shared with the team).
3localSettings/.qoder/settings.local.json (per-machine, personal; added to .gitignore).
4flagSettingsFile specified via the --settings CLI parameter.
5cliArg--allowed-tools / --disallowed-tools command-line parameters.
6commandIn-session commands such as /allow and /deny.
7sessionTemporary rules created at runtime ("Allow for this session" in a prompt).
Higher-precedence sources override lower ones. If the organizational policy enables allowManagedPermissionRulesOnly, only policy-managed rules are used.

Mode configuration

Set the default mode — configure general.defaultPermissionMode in ~/.qoder/settings.json:
{
  "general": {
    "defaultPermissionMode": "accept_edits"
  }
}
Disable YOLO mode — organization administrators can block users from entering bypass_permissions mode with the following configuration:
{
  "security": {
    "disableYoloMode": true
  }
}
Disable Plan mode — if you do not need the Plan workflow, you can turn it off:
{
  "general": {
    "plan": {
      "enabled": false
    }
  }
}
Auto mode classifier configuration — guide the AI classifier's tendencies with natural-language rules:
{
  "autoMode": {
    "allow": [
      "running npm/yarn/pnpm scripts defined in package.json",
      "creating or editing test files"
    ],
    "soft_deny": [
      "deleting files outside the test directory",
      "modifying CI/CD configuration"
    ],
    "environment": [
      "This is a Node.js monorepo with pnpm workspaces",
      "The project uses Vitest for testing"
    ]
  }
}
These rules are soft guidance — they are injected into the classifier prompt as reference, and the final decision is still made by the AI classifier. autoMode is loaded only from trusted sources (user-global settings and localSettings); project settings are excluded to prevent malicious privilege escalation.

Permission rule configuration

Qoder CN CLI enforces permissions through three core strategies: Allow, Deny, and Ask. The relevant configuration files, in increasing order of precedence, are:
~/.qoder/settings.json
${project}/.qoder/settings.json
${project}/.qoder/settings.local.json (typically added to .gitignore)
Rules are grouped under allow, ask, and deny:
{
  "permissions": {
    "allow": [
      "Read(/src/**)",
      "Edit(/src/**)",
      "Bash(npm run test:*)"
    ],
    "ask": [
      "Bash(npm publish:*)",
      "WebFetch"
    ],
    "deny": [
      "Read(*.pem)",
      "Bash(rm -rf:*)"
    ]
  }
}
Rule syntax:
FormMeaning
ToolNameApplies to the entire tool.
ToolName(content)Applies to a specific path, command, agent type, or other tool-specific content.
&#42;Matches all tools.
Use canonical tool names: Read, Edit, Write, Bash, Grep, Glob, WebFetch, WebSearch, Agent, along with MCP tool names such as mcp__github__create_issue. Command-line override:
qoderclicn --allowed-tools 'Read,Grep,Bash(git status)'
qoderclicn --disallowed-tools 'Bash(rm -rf:*),mcp__github__delete_repo'
qoderclicn --tools 'Read,Grep,Edit'

Trusted directories

Qoder CN CLI treats the current working directory (CWD) at startup as the primary trusted directory. Inside a trusted directory, file reads are allowed by default; file writes can be auto-approved in accept_edits and auto modes; and non-default permission modes (auto, bypass, and so on) can take effect. If the current directory is not trusted, Qoder CN CLI is forced back to default mode. Add additional trusted working directories via --add-dir, the /add-dir command, or permissions.additionalDirectories:
qoderclicn --add-dir ../shared
{
  "permissions": {
    "additionalDirectories": ["../shared"]
  }
}
Protected paths: Certain paths are protected, including .git, .vscode, .idea, .husky, most .qoder configuration files, shell startup files such as .bashrc/.zshrc, Git configuration, .mcp.json, and .ripgreprc. In regular interactive mode, these paths require explicit approval; in auto mode, they are denied.

File access rules

Read and Edit Read rules apply to all file-reading tools (such as Grep and Glob); edit rules apply to Edit, Write, and NotebookEdit. File rules use gitignore-style matching.
PatternMeaning
/src/&#42;&#42;Path relative to the rule source root. In project/local settings this is relative to the project root; in user settings it is relative to the home directory.
~/Documents/&#42;&#42;Path relative to the home directory.
//tmp/data/&#42;&#42;An absolute path starting from the system /; requires a double slash.
&#42;.secretA filename pattern without a root; matches at any location.

Bash rules

Bash(...) rules can match exact commands, command prefixes, or wildcard patterns:
  • Bash(npm run build) matches npm run build exactly.
  • Bash(npm run test:*) matches any command starting with npm run test.
  • Bash(git log *) uses glob-style wildcards.
Shell matching is conservative: deny and ask rules pass through common wrappers and environment-variable prefixes; prefix and wildcard allow rules do not silently approve compound commands; and dangerous commands (such as destructive deletion or force push) may force confirmation even when a broad allow rule exists. In auto mode, dangerous shell commands are denied.

Web and MCP rules

WebFetch restricts the domains that the web fetch tool can access. For example, WebFetch(domain:example.com) limits fetches to example.com. MCP MCP tools use the fully qualified name mcp__<server>__<tool>; you can use mcp__github__* to match all tools of a given server, or mcp__* to match all MCP tools. To restrict the run to specific MCP servers, use --allowed-mcp-server-names:
qoderclicn --allowed-mcp-server-names context7,github

Hooks and permissions

The Qoder CN CLI hook system has two injection points in the permission decision chain: PreToolUse (before tool execution) and PermissionRequest (after the permission pipeline produces ask, before the prompt is shown). Hook permission decisions take precedence over permission modes — even in bypass_permissions mode, a deny returned by a PreToolUse hook still blocks execution. See Hooks for details.

Worktree

Use --worktree [name] to start a Qoder CN CLI session in an isolated Git worktree. This is suitable for working on multiple tasks in parallel within the same repository, avoiding conflicts caused by multiple sessions sharing the same working directory.
Requirements: run the command inside a Git repository and ensure Git is installed locally.

Start in a worktree

qoderclicn --worktree feature-a
qoderclicn --worktree feature-a "Implement the login fix"
qoderclicn --worktree
If no worktree name is provided, Qoder CN CLI generates one automatically. Once the worktree is ready, Qoder CN CLI switches to it and starts the session normally. At the end of the session, Qoder CN CLI prints the worktree path and the command to resume it:
cd <worktree-path> && qoderclicn --resume <session-id>

Remove a worktree manually

To remove a worktree manually, run:
git worktree remove <worktree-path>

Memory

Qoder CN CLI reconstructs its context for each session. Knowledge that needs to be retained across sessions comes from two main types of memory:
  • AGENTS.md files: persistent instructions maintained by you or your team; suitable for development conventions, project structure, common commands, and collaboration agreements.
  • Auto-memory: Markdown memory that Qoder CN CLI saves locally when enabled; suitable for recording preferences, feedback, project background, and external references that remain useful in later sessions.
Memory is provided to the model as context, but it is not an enforced policy. To hard-block certain commands, tools, or paths, use permission configuration or hooks.

Common AGENTS.md locations

~/.qoder-cn/AGENTS.md
${project}/AGENTS.md
${project}/AGENTS.local.md
${project}/.qoder/rules/*.md
LocationPurposeSuitable for commit
~/.qoder-cn/AGENTS.mdGeneral cross-project preferences and habits for the current user.No
${project}/AGENTS.mdTeam-shared project rules, architecture notes, and common commands.Yes
${project}/AGENTS.local.mdProject-specific notes for the current machine, such as local service endpoints or personal test data.No
${project}/.qoder/rules/&#42;.mdProject rules split by topic or file scope.Yes
To use a different file name, set context.fileName to a single file name or an array of file names. The default value is AGENTS.md.

Loading logic

When Qoder CN CLI starts up or refreshes memory, project memory is looked up upward, checking the project rules directory at each level:
  • User-level memory: loads AGENTS.md from the user configuration directory.
  • Project and local project memory: within a trusted workspace, searches from the current workspace directory upward for AGENTS.md, AGENTS.local.md, and .qoder/rules/**/*.md, stopping by default at the directory containing .git.
  • Rules without a paths frontmatter are loaded together with project memory; rules with a paths frontmatter are loaded on demand only after Qoder CN CLI accesses a matching file.
  • Subdirectory memory: not preloaded at startup. Only after Qoder CN CLI successfully reads a file in a subdirectory does it walk up from that file's directory and load any memory files that had not been loaded before.

Rules

Rules are instruction files placed under the rules/ directory and split by topic, used as an alternative to a single, bloated AGENTS.md. Rules have two scopes:
ScopeLocationApplies toSuitable for commit
Project${project}/.qoder/rules/&#42;&#42;/&#42;.mdThe project containing the file; shared with the team.Yes
User~/.qoder-cn/rules/&#42;&#42;/&#42;.mdEvery project you open; personal to this machine.No
The optional paths frontmatter of a rule determines when it is loaded: without paths, it always applies; with paths, it applies according to the path. Example:
---
paths:
  - src/api/**
  - "**/*.test.ts"
---

# API rules

- Validate request bodies with the shared schemas under `src/api/schema/`.
- Every handler must return the standard error structure.

Management and auto-memory

In the TUI, enter /memory to open the memory overview and manage user-level, project-level, and local memory files; running /init generates AGENTS.md in the project directory. Auto-memory only runs in interactive sessions and is enabled through an environment variable:
QODER_MEMORY=1 qoderclicn
To also enable the cross-project, user-level auto-memory root, set both:
QODER_MEMORY=1 QODER_MEMORY_USER=1 qoderclicn
Project-level auto-memory is saved under ~/.qoder-cn/projects/<project>/memory/; when the user level is enabled, ~/.qoder-cn/memory/ is also used. Once enabled, you can open the auto-memory folder from the /memory panel, or enter /memory manage to manage the auto-saved memory files.

Importing other files

AGENTS.md can pull in other files with @path/to/file. Relative paths are resolved against the directory of the current AGENTS.md. Relative paths, absolute paths, and ~/ paths are supported; @... occurrences inside inline code or code blocks are not recognized as imports.
See @README.md for the high-level architecture.
Use @docs/testing.md for test data setup.

Subagents

A subagent is an agent in Qoder CN CLI specialized for a particular type of task. Each subagent has its own conversation context, tool set, model configuration, permission mode, and runtime limits, making it suitable for delegating focused work such as code exploration, solution design, interface review, and test coverage. In the TUI, run /agents to open the configuration panel to view, create, and manage subagents. For full capabilities, source precedence, configuration fields, and usage, see Subagents.

Commands

Commands (slash commands) are shortcuts in Qoder CN CLI for triggering specific tasks, invoked with a slash (/) prefix. In TUI mode, entering / shows the list of available commands to select and run; headless mode also supports running commands that submit prompts.

Command types

TypeDescriptionSupported modesExtensibility
TUI typeProvides an interactive interface (such as pop-up dialogs and list selection).TUISystem built-in; not user-extensible.
Prompt typeSubmits a predefined prompt to the conversation, guiding the CLI to complete a specific task.TUI + HeadlessSupports user-defined extensions.
Example of running a command in headless mode:
# Run a command (with additional instructions)
qoderclicn -p '/review focus on comment coverage'

# Run a custom prompt command
qoderclicn -p '/git-commit'

Built-in commands

Common built-in commands provided by Qoder CN CLI:

Command

Type

Purpose

/agents

TUI

View and manage the subagent list; supports creating and editing subagent configurations.

/tasks

TUI

View and manage background tasks.

/workflows

TUI

Open the dynamic workflow task panel.

/clear

TUI

Clear the current conversation and start a new one.

/commands

TUI

View and manage custom commands; supports creating and editing command configurations.

/compact

Prompt

Compact the conversation history; can specify a focus area.

/config

TUI

Configuration management; view or modify Qoder CN CLI configuration items.

/export [filename]

TUI

Export the current session to a file.

/feedback

TUI

Submit feedback or report an issue.

/help

TUI

Show help information.

/init

TUI

Initialize the project by analyzing its structure and generating the AGENTS.md memory file.

/login

TUI

Log in to your Qoder CN CLI account.

/logout

TUI

Log out of your Qoder CN CLI account.

/mcp

TUI

MCP service management.

/memory

TUI

Open the memory overview; when auto-memory is enabled, open the auto-memory folder, or use /memory manage to manage topic files.

/model

TUI

View and manage model-level settings.

/effort [level]

TUI

Set the reasoning depth of the current model; without a level, opens the model parameter panel.

/context-window

TUI

Set the context window of the current model; without arguments, opens the model parameter panel.

/fast [on|off]

TUI

Toggle fast mode for the current model; without arguments, opens the model parameter panel.

/quest

Prompt

Intelligent workflow orchestrator; multiple agents work together to help the user complete feature development.

/quit

TUI

Exit Qoder CN CLI.

/release-notes

TUI

View version release notes.

/resume

TUI

Resume a previous session or conversation history; supports Tab to page through sessions.

/review

Prompt

Run a code review to check code quality and conformance.

/setup-github

TUI

GitHub integration configuration for setting up GitHub-related features.

/skills

TUI

Manage Skill commands for the current workspace.

/status

TUI

View the current session status and system information.

/upgrade

TUI

Upgrade your subscription plan.

/usage

TUI

View usage statistics, including token consumption.

/vim

TUI

Enable or configure Vim mode for a Vim-style editing experience.

Create custom commands

Qoder CN CLI supports creating Prompt-type custom commands whose name, description, and system prompt are defined through a configuration file. The configuration file is in Markdown format and contains frontmatter metadata and a system prompt:
---
name: command-name
description: Description of what the command does; shown in the TUI command list.
---

This is the system prompt content for the command. When the user runs this command, this prompt is submitted to the conversation to guide the CLI to complete the specific task.
Field descriptions: name (required) — the unique name of the command, used for /command-name invocation; description (required) — the functional description of the command, supporting multi-line text (using YAML syntax). Naming conventions: use lowercase letters and hyphens (for example, git-commit); avoid spaces and special characters; it is recommended that the file name match the name field; commands in subdirectories use : as a namespace separator (for example, commands/git/commit.md is registered as /git:commit); if a SKILL.md exists in the same directory, that directory is registered as a single command, and any sibling .md files are ignored.

Storage locations and precedence

Command configuration files can be stored in project-level or user-level directories:
LevelPathApplies toCommit to repository
Project.qoder/commands/<command_name>.mdCurrent project only.Recommended (team-shared).
User~/.qoder-cn/commands/<command_name>.mdAll projects.Not committed (personal configuration).
Precedence: if a command of the same name exists at both project and user levels, the project-level command takes precedence. When Qoder CN CLI is already running, run /commands to reload after adding or modifying a command configuration file.

Example

Define a command as follows and save it to ~/.qoder-cn/commands/quest.md.
---
name: quest
description: "Intelligent workflow orchestrator that guides users through feature development using specialized subagents"
---

First use the design subagent to complete the system design, then use the code-review subagent to perform a code review.
In TUI mode, enter /quest to trigger the command; during execution, the two subagents are invoked in order as specified by the prompt.