Beginner’s Guide to CLI AI Agents: Installation and First Conversation

    This guide explains what command-line AI agents can do, who should use them, and how to prepare the environment before installation. It covers installing Node.js, connecting a model service, trying safe practice tasks, and following security checks before running commands or sharing error messages.

    Beginner’s Guide to CLI AI Agents: Installation and First Conversation

    1. What Command-Line AI Agents Can Do

    Many people hear “command-line AI coding assistant” and assume it is only a tool for developers who write code. In practice, its use cases are broader. These tools run in a terminal, understand requests written in natural language, read local files, call scripts, and invoke other command-line utilities to complete repeated computer tasks for you.

    Common scenarios include:

    • Q&A and writing: organizing information, polishing documents, and drafting initial reports.
    • Web and small development tasks: building a simple static page from scratch or adding a feature module to an existing project.
    • Data processing: reading spreadsheets, cleaning data, producing statistical conclusions, and generating plotting scripts.
    • Batch file operations: for example, splitting a payroll table with hundreds of rows into separate files per person. Such work used to require scripting and manual verification; now a clear instruction can get the process started.
    • Multimedia processing: using open-source tools already installed on the system to combine audio and images into a video.

    The main requirement is the ability to describe a task in natural language, not the ability to write code. However, because these agents can execute system commands, you need a few basic conditions before using them. These are covered in the next section.

    2. Who Should Use CLI AI Agents, and Who Should Not

    Suitable for:

    • People willing to spend about an hour on installation and follow the steps one by one.
    • People with large amounts of repetitive work involving files, spreadsheets, or text who want an automation approach.
    • People who can recognize risky commands and are willing to review them before execution.

    Not suitable for now:

    • People who do not want to use a terminal at all and need a ready-to-use graphical interface.
    • People handling confidential or highly sensitive data who cannot use a locally deployed model.
    • People whose network cannot reliably reach the selected model service.

    3. Three Preparations Before Installation

    Before installing, check the three items below one by one. If you skip them, the most common result is an error during installation, which can be time-consuming to troubleshoot.

    3.1 Network and Model Service

    The agent itself is mainly a shell. The model behind it is responsible for understanding and reasoning. You need to choose a model source:

    • Cloud models: when using external services, make sure you have stable and compliant network access according to your location, organization, and applicable rules. Inference services offered by cloud providers may be directly accessible depending on your environment.
    • Open-source models or local deployment: data stays on your machine and does not depend on external networks, but better GPU or memory may be required. Results also depend on model size.

    No matter which option you choose, it is recommended to test the API with a simple request first. Continue only after confirming that connectivity works.

    3.2 Install Node.js

    Most command-line AI agents are distributed through package managers such as npm, so you need Node.js first.

    1. Open the official Node.js website and download the current Long-Term Support (LTS) version. Check the minimum version required in the official documentation of the agent you choose; many tools require Node.js 18 or later.
    2. If you are on Windows, keep the option to add Node.js to the environment variables during installation.
    3. After installation, reopen the terminal and run the following commands:
    1. node -v
    2. npm -v

    If both commands print version numbers, the installation succeeded. If you see “not recognized as an internal or external command” or “command not found”, it is usually because you did not reopen the terminal or the environment variables did not take effect.

    3.3 Windows Users: Install Git for Windows

    Some operations performed by the agent rely on a Unix-like shell environment. On Windows, installing Git for Windows can significantly reduce compatibility issues because it includes Git Bash.

    During installation, keep the default options and make sure Git is added to the PATH environment variable. You do not need to learn Git usage for this step; simply installing it is enough.

    4. Installation: Two Methods and Troubleshooting

    Step 1: Open a Terminal

    • Windows: search for Terminal or PowerShell in the Start menu and open it.
    • macOS: open Terminal from Applications > Utilities.
    • Linux: you can usually open it with Ctrl + Alt + T.

    A terminal looks like a text window with a dark background. You can think of it as a dialog interface without graphics. All subsequent operations will be performed here.

    Step 2: Install with a Package Manager

    Run the global installation command in the terminal. The following is a real npm installation example using @anthropic-ai/claude-code, the package name for Claude Code:

    1. npm install -g @anthropic-ai/claude-code

    When using other tools, replace the package name with the one specified in the official documentation for that tool. An incorrect package name can cause installation to fail or install the wrong program. After installation, check the version by running the tool’s command name followed by --version, for example claude --version.

    Common errors during installation and their fixes:

    • Insufficient permissions: On Windows, close the terminal and reopen it as administrator, then run the installation again. On macOS or Linux, avoid simply adding sudo in front of the command if possible. A safer approach is to move npm’s global installation directory to a location writable by your current user and reinstall.
    • Network timeout: First check system proxy or organizational network settings. If downloads are very slow, you can switch npm’s registry to a trusted mirror that is appropriate for your environment, then confirm the current address with npm config get registry.
    • Version conflict: If the error mentions dependency resolution failure, your Node.js version may be too old. Upgrade to the LTS version, remove the failed installation records, and try again.

    When an error occurs, read the full error message first; it often already contains the cause. If you still cannot resolve it, you can ask an AI chat tool to analyze the error message. Before doing so, redact sensitive information as described in Section 7.

    Step 3: Script Installation (Alternative Method)

    If installation with a package manager fails, official documentation for many agents also provides an installation script. macOS, Linux, and WSL users may see commands similar to this:

    1. curl -fsSL <official installation script URL> | bash

    This command pipes remote content directly into bash, so you cannot inspect what it does before execution. It is not recommended to copy and run it blindly. A safer approach is to follow four steps:

    1. Find the script URL in the official documentation and confirm that the domain truly belongs to the official site of the tool.
    2. Download it locally without executing it immediately:
    1. curl -fsSL <official installation script URL> -o install.sh
    1. Open the file and read it to confirm that it only performs installation-related actions and does not delete files or upload data.
    2. If the official documentation provides a SHA256 checksum, calculate and compare it:
    1. sha256sum install.sh

    After verification, run bash install.sh. When finished, restart the terminal and enter the launch command for the agent. If an interactive welcome screen appears, the installation succeeded.

    5. First Launch: Connect a Model

    On first launch, the tool will usually ask you to configure a model service. Common approaches are to set an API endpoint and key, or to specify a locally deployed model address.

    When configuring keys, use environment variables rather than writing them directly into configuration files or scripts. This prevents keys from being exposed when files are shared or committed to a code repository.

    The following table compares the two approaches:

    Item Cloud model Local open-source model
    Data security Data is sent to the service provider Data stays on the local machine
    Cost Charged by usage Mainly hardware investment and electricity
    Response speed Depends on network conditions Depends on local hardware performance
    Network requirement Requires stable access to the service Generally independent of network
    Suitable for Users who prioritize quality and do not handle sensitive data Users who handle sensitive materials and have local hardware

    6. Four Practice Tasks

    Do not start by asking the agent to handle a complex project. Try the tasks below in order. Confirm that each step works before moving to the next.

    1. Pure conversation: Ask a technical question you are familiar with, such as “Explain what branches are in Git.” This step only verifies model connectivity.
    2. Single-file operation: Put a text file in a separate test folder and ask the agent to read it and summarize the key points. Use a sample file you created yourself, not an important document.
    3. Generate a small script: Ask it to write a small tool, such as one that counts files of different types in a folder. Run it and check the result.
    4. Multi-step task: Practice splitting with a sample CSV. The steps are:
      • Copy the sample file into a dedicated practice directory. Do not modify the original file.
      • Restrict the output directory in the instruction, for example, “You may only write files to the practice/output directory.”
      • Ask it to list the plan first and execute only after confirmation. You can use a prompt like: “First list each command you plan to run, and wait for my confirmation before starting.”

    7. Safety Checklist

    Because an agent can execute system commands, one wrong instruction can delete or overwrite files. Check each item below when using it:

    • Review commands before confirming them: especially commands that delete, overwrite, change permissions, or move files.
    • Restrict the working directory: allow the agent to operate only within a specified project folder. Do not open the entire user directory to it.
    • Do not run scripts from unknown sources: do not use sudo to run unfamiliar code simply because an AI suggested it.
    • Back up before operating: before batch operations on important directories, make a copy first so you can roll back.
    • Keep keys private: do not put API keys, customer data, or identity information into prompts, and do not paste them into cloud models.
    • Redact before asking for help with errors: before sending an error message to any AI tool, remove API keys, usernames, personal directory names in absolute paths, IP addresses, and customer data. If sensitive information cannot be fully removed, use a local model instead or seek help from a trusted channel.

    8. Conclusion

    CLI AI agents greatly shorten the distance between “describing a need” and “completing a task.” Preparing the environment and troubleshooting installation may take your first hour, but it is a one-time investment. After that, large amounts of repetitive text, spreadsheet, and file work can be handled by the agent.

    Bookmark this guide and follow it step by step. After each step, confirm the result before continuing.