mirror of https://github.com/QwenLM/qwen-code.git synced 2026-07-25 17:04:42 +00:00

feat(installer): verify release assets + switch public docs to standalone entrypoint (#3855 )

* fix(installer): tighten verifier base-url + clarify test helper

Three small refinements from the second review pass:

- normalizeHttpsBaseUrl rejects everything except https, since real release
  URLs are always HTTPS. Accepting http previously would let an operator
  silently target a stale or attacker-controlled mirror.
- Drop EXPECTED_RELEASE_ASSET_NAMES from the public exports; it was only
  used internally for the verification log line.
- Rename the test helper standaloneChecksumContent to
  placeholderChecksumContent and document that the hashes in its output are
  placeholders — the remote verifier does not download archives or compare
  hashes, it only validates that SHA256SUMS lists the expected names and
  that each archive URL is reachable.

The non-https rejection test now also covers `http://` in addition to the
existing `file://` case.

* style(installer): align installer completion output

* revert(installer): keep hosted installer output unchanged

* fix(installer): address release validation review feedback

* docs: switch public install commands to standalone hosted entrypoint

Update README, quickstart, and overview to point at the new
install-qwen-standalone.sh / install-qwen-standalone.ps1 hosted URLs.
Add standalone uninstall instructions to Uninstall.md. Remove the
staged-rollout note from INSTALLATION_GUIDE.md since the hosted
installers and release archive sync are now validated in production.

* docs: clarify pull request size guidance

* fix(installation): harden standalone release validation

* fix(installation): redact release verifier credentials

* feat(installer): add visual branding to Linux/macOS install script

Add brand-colored ASCII art logo, custom download progress bar with
Unicode block characters, and step indicators [1/3] [2/3] [3/3] to
match the quality of competing CLI installers.

* fix(test): update stale assertion after guide text was removed

The text "Public installation documentation" was removed in 20f5243f6
but the test assertion was not updated, causing a persistent failure.

* feat(installer): use truecolor per-character gradient for logo branding

Replace 256-color block coloring with 24-bit truecolor per-character
gradient interpolation matching the CLI's ink-gradient rendering.
Colors follow the fallback gradient: #4796E4 → #847ACE → #C3677F.
Remove unused BRAND_ROSE variable and switch step indicators to
BRAND_BLUE for consistency.

* fix(installer): address critical review findings on SSRF, semver, and reliability

- Fix IPv4-mapped IPv6 SSRF bypass: handle 3-part hex representations
  that Node.js produces (e.g. ::ffff:0:7f00:1)
- Reject empty hostname in isPrivateOrReservedHost
- Strip query params in redactUrlForLog to prevent credential leakage
  from signed URLs in CI logs
- Tighten bat semver regex: require '.' or '-' separator before suffix
  (rejects 1.2.3foo, matches shell installer behavior)
- Add -f flag to curl in download_with_progress so HTTP errors aren't
  silently written as file content
- Restore terminal cursor in INT/TERM signal handlers (RETURN trap
  doesn't fire on exit)
- Add unit tests for isPrivateOrReservedHost and redactUrlForLog
- Update test assertion for new split-pattern semver validation

* fix(installer): close release validation review gaps

* test(installer): cover shadowed qwen installs

* fix(installer): avoid npm auto-update for standalone installs

* fix(installer): block IPv4-compatible IPv6 SSRF and harden archive validation [skip ci]

- Add ipv4FromCompatibleIpv6() to detect deprecated RFC 4291 §2.5.5.1
  addresses (e.g. ::7f00:1 → 127.0.0.1) that bypass SSRF protection
- Extend archive validation to reject hardlinks in addition to symlinks
- Add signal trap suppression during critical mv swap to prevent
  partial-install state on Ctrl+C
- Add diagnostic logging to silent catch in standalone detection

* fix(installer): finish standalone install follow-ups

* feat(installer): streamline output with custom progress bar and minimal UX

Replicate OpenCode-style installer experience:
- Add custom ■-character progress bar with percentage (file-size polling)
- Remove verbose INFO:/SUCCESS: prefixes on happy path
- Simplify --help output to essential options
- Keep gradient logo, shadowing warnings, and PATH conflict detection
- Silence mirror probing, checksum, and npm detection messages
- Add "For more information" link to final output

Both .sh and .bat scripts updated consistently.
All 95 tests pass.

* feat(installer): add progress bar and logo to Windows installer

- Add PrintLogo subroutine with QWEN CODE ASCII header
- Add PrintProgressComplete using PowerShell VT100 ■-bar at 100%
- Show progress complete after successful download
- Add spacing in PrintHeader for consistent look with .sh

* fix(installer): address review findings on progress bar

- Replace `sleep 0.3` with `sleep 1` for busybox/minimal env compatibility
- Add file_size > 0 guard to avoid progress bar flicker on empty file
- Remove trailing blank lines before closing braces in 4 functions

* fix(installer): finalize Windows UX — suppress curl progress, fix logo

- Windows: suppress curl ### progress with -s --show-error (keep -#fSLo for test compat)
- Windows: use simple colored "Q W E N  C O D E" logo (truecolor VT100)
- Windows: SHA256SUMS download uses DownloadFileQuiet (no progress bar for small files)
- Windows: remove SUCCESS/INFO PATH messages from MaybeUpdateUserPath
- Linux: fix double 100% progress bar (skip bar for files < 100KB)

* fix(installer): handle Windows backslash paths in standalone detection

`fs.realpathSync` returns backslash paths on Windows (e.g. C:\Users\...\lib\cli.js).
Normalize to forward slashes before matching the /lib/cli.js suffix so standalone
install detection works correctly on Windows.

Fixes CI: Test (windows-latest, Node 22.x)

* fix(installer): normalize expected paths in Windows standalone test

The existsSync mock built expected paths with path.join() which produces
backslashes on Windows, but then compared against a forward-slash-normalized
candidate. Use template literals with forward slashes for the expected
array so both sides match on all platforms.

* refactor(installer): simplify post-install output

Remove verbose post-install messages (install path, uninstall command,
PATH conflict warnings, npm coexistence tips) and replace with a clean
4-line summary matching OpenCode's minimal style.

* refactor(installer): simplify Windows post-install output

Match the Linux/macOS installer simplification — remove verbose
messages (install path, uninstall command, PATH warnings) and keep
only the essential 4-line success summary.

* refactor(installer): suppress verbose Windows messages

Remove "User PATH already starts with", backup WARNING messages,
and PS1 wrapper "Run: qwen" / "qwen is ready to use" output to
match the minimal Linux installer style.

* fix(test): align install-script assertions with simplified output format

The installer scripts were refactored to use a compact output format
(no separate To start/Installed to/Uninstall lines, no shadow warnings),
but the test assertions were not updated accordingly.

* fix(installer): align hardlink detection and expand test coverage

- Rename archive_contains_symlinks to archive_contains_symlinks_or_hardlinks
  in install-qwen-with-source.sh and extend the awk pattern from ^l to ^[lh]
  to also reject hardlinks in archives, aligning with the standalone installer.

- Add macOS (darwin-arm64) standalone detection test and malformed
  manifest.json fallback test in installationInfo.test.ts.

- Add edge-case tests for isPrivateOrReservedHost: decimal-encoded IPs,
  octal-encoded IPs, IPv6 zone IDs, and empty brackets.

2026-06-04 17:23:04 +08:00

8.3 KiB

Raw Permalink Blame History

Quickstart

👏 Welcome to Qwen Code!

This quickstart guide will have you using AI-powered coding assistance in just a few minutes. By the end, you'll understand how to use Qwen Code for common development tasks.

Before you begin

Make sure you have:

A terminal or command prompt open
A code project to work with
An API key from Alibaba Cloud Model Studio (Beijing / intl), or an Alibaba Cloud Coding Plan (Beijing / intl) subscription

Step 1: Install Qwen Code

To install Qwen Code, use one of the following methods:

Quick Install (Recommended)

Linux / macOS

curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.sh | bash

Windows

irm https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.ps1 | iex

Note

It's recommended to restart your terminal after installation to ensure environment variables take effect.

Manual Installation

Prerequisites

Make sure you have Node.js 22 or later installed. Download it from nodejs.org.

NPM

npm install -g @qwen-code/qwen-code@latest

Homebrew (macOS, Linux)

brew install qwen-code

Step 2: Set up authentication

When you start an interactive session with the qwen command, you'll be prompted to configure authentication:

# You'll be prompted to set up authentication on first use
qwen

# Or run /auth anytime to change authentication method
/auth

Choose your preferred authentication method:

Alibaba Cloud Coding Plan: Select Alibaba Cloud Coding Plan for a fixed monthly fee with diverse model options. See the Coding Plan guide (intl) for setup instructions.
API Key: Select API Key, then enter your API key from Alibaba Cloud Model Studio (Beijing / intl). See the API setup guide (Beijing / intl) for details.

⚠️ Note: Qwen OAuth was discontinued on April 15, 2026. If you were previously using Qwen OAuth, please switch to one of the methods above.

Note

When you first authenticate Qwen Code with your Qwen account, a workspace called ".qwen" is automatically created for you. This workspace provides centralized cost tracking and management for all Qwen Code usage in your organization.

Tip

To configure authentication, start Qwen Code and run /auth. Use /doctor to check your current configuration at any time. See the Authentication page for details.

Step 3: Start your first session

Open your terminal in any project directory and start Qwen Code:

# optiona
cd /path/to/your/project
# start qwen
qwen

You'll see the Qwen Code welcome screen with your session information, recent conversations, and latest updates. Type /help for available commands.

Chat with Qwen Code

Ask your first question

Qwen Code will analyze your files and provide a summary. You can also ask more specific questions:

explain the folder structure

You can also ask Qwen Code about its own capabilities:

what can Qwen Code do?

Note

Qwen Code reads your files as needed - you don't have to manually add context. Qwen Code also has access to its own documentation and can answer questions about its features and capabilities.

Make your first code change

Now let's make Qwen Code do some actual coding. Try a simple task:

add a hello world function to the main file

Qwen Code will:

Find the appropriate file
Show you the proposed changes
Ask for your approval
Make the edit

Note

Qwen Code always asks for permission before modifying files. You can approve individual changes or enable "Accept all" mode for a session.

Use Git with Qwen Code

Qwen Code makes Git operations conversational:

what files have I changed?

commit my changes with a descriptive message

You can also prompt for more complex Git operations:

create a new branch called feature/quickstart

show me the last 5 commits

help me resolve merge conflicts

Fix a bug or add a feature

Qwen Code is proficient at debugging and feature implementation.

Describe what you want in natural language:

add input validation to the user registration form

Or fix existing issues:

there's a bug where users can submit empty forms - fix it

Qwen Code will:

Locate the relevant code
Understand the context
Implement a solution
Run tests if available

Test out other common workflows

There are a number of ways to work with Qwen Code:

Refactor code

refactor the authentication module to use async/await instead of callbacks

Write tests

write unit tests for the calculator functions

Update documentation

update the README with installation instructions

Code review

review my changes and suggest improvements

Tip

Remember: Qwen Code is your AI pair programmer. Talk to it like you would a helpful colleague - describe what you want to achieve, and it will help you get there.

Essential commands

Here are the most important commands for daily use:

Command	What it does	Example
`qwen`	start Qwen Code	`qwen`
`/auth`	Change authentication method (in session)	`/auth`
`/doctor`	Check current authentication and environment	`/doctor`
`/help`	Display help information for available commands	`/help` or `/?`
`/compress`	Replace chat history with summary to save Tokens	`/compress`
`/clear`	Clear terminal screen content	`/clear` (shortcut: `Ctrl+L`)
`/theme`	Change Qwen Code visual theme	`/theme`
`/language`	View or change language settings	`/language`
→ `ui [language]`	Set UI interface language	`/language ui zh-CN`
→ `output [language]`	Set LLM output language	`/language output Chinese`
`/quit`	Exit Qwen Code immediately	`/quit` or `/exit`

See the CLI reference for a complete list of commands.

Pro tips for beginners

Be specific with your requests

Instead of: "fix the bug"
Try: "fix the login bug where users see a blank screen after entering wrong credentials"

Use step-by-step instructions

Break complex tasks into steps:

1. create a new database table for user profiles
2. create an API endpoint to get and update user profiles
3. build a webpage that allows users to see and edit their information

Let Qwen Code explore first

Before making changes, let Qwen Code understand your code:

analyze the database schema

build a dashboard showing products that are most frequently returned by our UK customers

Save time with shortcuts

Press ? to see all available keyboard shortcuts
Use Tab for command completion
Press ↑ for command history
Type / to see all slash commands

Getting help

In Qwen Code: Type /help or ask "how do I..."
Documentation: You're here! Browse other guides
Community: Join our GitHub Discussion for tips and support

8.3 KiB Raw Permalink Blame History