Help Center/ CodeArts Agent/ User Guide (CLI)/ Custom Commands
Updated on 2026-07-29 GMT+08:00
View PDF
Share

Custom Commands

In addition to built-in slash commands, file references, and Bash commands, you can also add custom commands by defining them in .jsonc and .md files. For details, see Customizing Commands in .jsonc and Customizing Commands in .md.

Customizing Commands in .jsonc

CodeArts Agent CLI allows you to configure custom commands in codearts_cli.json or codearts_cli.jsonc (JSON file with comments).

You can configure custom commands under personal-level or project-level paths. For details, see Table 1.

You need to manually create a file and define custom commands in it. Then, run CodeArts Agent CLI.

Table 1 Configuration path

Configuration Level

Description

Location

Personal-level

The personal-level configuration is the global default configuration. You can set personal preferences (such as themes or shortcuts), which will take effect for all projects.

~/.codeartsdoer/codearts_cli.json or ~/.codeartsdoer/codearts_cli.jsonc

The tilde (~) indicates the home directory of the current user. In Windows, it is equivalent to C:\Users\Username\. In macOS, it is equivalent to /Users/Username/. In Linux, it is equivalent to /home/Username/.

Project-level

The project-level configuration is dedicated to a specific project. It has a higher priority than the personal-level configuration and can overwrite it. This configuration is used to define unified rules for a project.

Project root directory/.codeartsdoer/codearts_cli.json or Project root directory/.codeartsdoer/codearts_cli.jsonc

Configuration Example

The following uses the custom commands test and check as examples.

  1. Use the project-level configuration and Windows as an example.

    Create the codearts_cli.jsonc file in the ./.codeartsdoer directory of the project root directory and configure the file as follows:

    In the custom commands, command name and template are mandatory.

    {
  //Command configuration
  "command": {
    // All custom commands are defined here.
    "test": {
      // command name = test. You can rename it to run, fix, or others as you like.
      "template": "This is the prompt sent to the AI after configuration. It can be a sentence or a complex instruction.",
      "description": "A brief description of the command, displayed in the TUI command list.",
      "agent": "Name of the AI agent that executes the command. This parameter is optional.",
      "model": "Model ID specified for the command. This parameter is optional and will overwrite the default model.",
      "subtask": false // Optional Boolean attribute, which is used to control whether the command runs in the sub-agent mode.
    },
    // Example of the second custom command: check
    "check": {
      "template": "Dedicated AI prompt for the run command, which is used to run the project and check code.",
      "description": "One‑click code check and project execution.",
      "agent": "",
      "model": "",
      "subtask": false
    }
  }
}

  2. Check whether the custom commands have taken effect.

    • In TUI development mode, enter /test to verify the custom command test. You can also enter /check to verify the custom command check.
      Figure 1 Example of the TUI development mode

    • In the CMD, PowerShell, or terminal, run the codearts run check command to associate the custom command check. You can also run the codearts run test command to associate the custom command test.

      The command output may vary. Refer to the actual output for the final result.

Customizing Commands in .md

Priority: If the command names are the same, the custom .md file has a higher priority than the .json file.

You can customize a Markdown file in the commands directory to define custom commands. The file name is the command name.

Table 2 Path of the commands folder

Level

Location

Personal-level

~/.codeartsdoer/commands

The tilde (~) indicates the home directory of the current user. In Windows, it is equivalent to C:\Users\Username\. In macOS, it is equivalent to /Users/Username/. In Linux, it is equivalent to /home/Username/.

Project-level

Project root directory/.codeartsdoer/commands

Configuration Example

  1. In Windows, create test.md under ~\.codeartsdoer\commands and add personal-level custom commands to the file. 

    ---
description: Task description, running tests with coverage
agent: build
model: huaweicloud-maas/GLM-5.1
---
Perform a full test and generate a coverage report. Locate the failed test cases and provide fix suggestions.

  2. Restart CodeArts Agent CLI.

    • In TUI development mode, enter /test to associate the custom command test.
      Figure 2 Example of the TUI development mode
    • In the CMD, PowerShell, or terminal, run the codearts run test command to associate the custom command test.

      The command output may vary. Refer to the actual output for the final result.