aliyun appmanager

--non-interactive

--output json

/alibabacloud-ecs-code-deploy

cd

EXECUTION ORDER: The Agent MUST follow the "Complete Deployment Workflow" section at the bottom of this document for the correct execution sequence. The Task sections below are organized by topic for reference — their numbering does NOT imply execution order.

Todo list (Deploy to Alibaba Cloud ECS):
  [ ] 0. Resolve $SKILL_DIR (cross-platform path — MUST run first; see "Step 0" below)
  [ ] 1. Environment pre-check (MUST run deploy_toolkit.py check; manual commands FORBIDDEN as replacement)
  [ ] 2. Obtain project (clone git URL here if needed; skip for local projects)
  ── Check whether .appmanager/config.yaml already exists (repeat-deploy shortcut) ──
  │  Exists + new ECS (no instanceId)      → skip 3-5, start from 5.5 (price check)
  │  Exists + existing ECS (has instanceId) → skip 3-5.5, jump to 6 (deploy)
  │  Does not exist                        → proceed normally from 3
  ───────────────────────────────────────────────────────────────────────────────
  [ ] 3. Read project (README.md -> quick-deploy method) + identify type (agent / app)
  [ ] 4. Ask user for deployment config (region + new ECS / existing ECS)
  [ ] 5. Init + generate scripts (appmanager init -> write start/stop scripts to config.yaml)
  [ ] 5.5. Pre-deploy price check + risk warning (MUST run deploy_toolkit.py price; confirm price / OSS billing / existing-ECS impact / group overwrite item by item)
  [ ] 6. Deploy (MUST run deploy_toolkit.py deploy; manual deploy command FORBIDDEN as replacement)
  [ ] 7. Verify (MUST run deploy_toolkit.py verify; manual status command FORBIDDEN as replacement)
  [ ] 8. Output final result (console link + cost reminder + management commands)

⛔ SCRIPT-FIRST RULE: Steps 1, 5, 6, 7 have a dedicated toolkit script at

$SKILL_DIR/scripts/deploy_toolkit.py

(where

$SKILL_DIR

is resolved in Step 0 below — works on Qoder, Claude Code, and any other platform). The Agent MUST run the corresponding subcommand DIRECTLY as the FIRST and ONLY action for that step — NEVER run manual CLI commands (like

aliyun version

, version checks, credential checks) BEFORE or INSTEAD of the script. The script already handles ALL checks internally. Manual commands are ONLY allowed as fallback if the script file itself does not exist.

❌ WRONG (Step 1): Run

aliyun version

→ check version → run

~/.aliyun/appmanager-venv/bin/python ...

→ check version → THEN run

deploy_toolkit.py check

✅ CORRECT (Step 1): Run

python3 "$SKILL_DIR/scripts/deploy_toolkit.py" check

→ if exit 1, fix the issue it reports → if script file missing, THEN fall back to manual checks

Item 6 is NON-NEGOTIABLE. An Agent that skips log verification and directly outputs "deployment succeeded" has NOT completed this skill correctly. If

deploy_toolkit.py verify

exits 1 (failed), the Agent MUST fix the issue and re-deploy before proceeding to item 7.

The toolkit script lives at

<skill-root>/scripts/deploy_toolkit.py

. Different platforms install skills to different locations (Qoder/Claude Code/Qwen/...). The Agent MUST resolve the absolute skill root once at session start and reuse it everywhere

$SKILL_DIR

appears below. Hardcoding any platform-specific path is FORBIDDEN.

export + test -f

• ✅ Pattern A (persistent shell):

  export SKILL_DIR="/abs/path"

  then later

  python3 "$SKILL_DIR/scripts/deploy_toolkit.py" <sub>

• ✅ Pattern B (fresh shell per call): inline the absolute path —

  python3 "/abs/path/scripts/deploy_toolkit.py" <sub>

• ⛔ Anti-pattern:

  SKILL_DIR=/path python3 "$SKILL_DIR/..."

  — outer shell expands

  $SKILL_DIR

  BEFORE the prefix assignment, producing

  /scripts/deploy_toolkit.py

  and ENOENT. If you see

  python3: can't open file '/scripts/deploy_toolkit.py'

  , switch to Pattern A or B.

python3 "$SKILL_DIR/scripts/deploy_toolkit.py" check

MUST — Handling unmet environment prerequisites: When

check

exits 1 because the aliyun CLI is missing or older than 3.3.19 (or appmanager-cli is missing/outdated), the Agent MUST NOT stop the workflow silently. The required flow is:

1. CLI NOT installed → Auto-install directly without asking user — execute the install command (see snippet below or references/init-and-credentials.md for the right arch), then re-run

   deploy_toolkit.py check

   to confirm.
2. CLI already installed → ASK the user first — show the detected version + the required version + the upgrade command, and ask for explicit consent (e.g. "aliyun CLI 3.3.4 is already installed but below the required >= 3.3.19 for appmanager; approve upgrade (overwrite-install into /usr/local/bin, requires sudo)?"). Never assume yes; never paste credentials.
   • On approval — execute the install/upgrade command, then re-run

     deploy_toolkit.py check

     to confirm.
   • On refusal — stop with the refusal as the reason. Do NOT continue with the older version (deployment will fail anyway).

The toolkit's

check

output already includes an

→ AGENT: DO NOT stop. ASK user ...

line for each fixable issue — follow it verbatim (except for the "not installed" case, which is auto-handled).

MUST — Upgrade method priority (avoid the "repeated upgrade" pitfall:

/usr/local/bin/

is often shadowed by earlier PATH entries like

/opt/homebrew/bin

):

1. brew-managed (

   check

   prints "managed by Homebrew") ->

   brew upgrade aliyun-cli

   ; do NOT overwrite

   /usr/local/bin/

   again.
2. sudo available -> overwrite into

   /usr/local/bin/

   , then verify:

   hash -r && which -a aliyun && aliyun version

   .
3. No sudo -> install to

   ~/bin/

   , ask user to approve appending

   export PATH="$HOME/bin:$PATH"

   to

   ~/.zshrc

   /

   ~/.bashrc

   .

After install/upgrade, ALWAYS rerun

deploy_toolkit.py check

to confirm. If

which -a aliyun

still shows the old binary first, fix PATH order — DO NOT repeat the same overwrite.

⛔ MUST configure AI-Mode: Agent MUST ensure AI-Mode is properly configured before running any

aliyun appmanager

commands.

deploy_toolkit.py check

handles this internally; the commands below are for manual fallback only.

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-ecs-code-deploy"
aliyun plugin update
aliyun configure ai-mode show   # verify: enabled=true, user-agent set
aliyun configure ai-mode disable # only when troubleshooting

deploy_toolkit.py check

⛔ PREFER OAuth OVER AK: This skill SHOULD guide users to use OAuth authentication as the PRIMARY method for providing Alibaba Cloud permissions. OAuth is more secure and convenient than AccessKey (no long-term secret storage needed). The Agent MUST present OAuth as the first option before mentioning AK-based methods.

OAuth Login Guide: Instruct the user to run the following command in their terminal:

bash

aliyun configure --mode OAuth --profile oauth

This is an interactive command that will:

1. Open a browser with an authorization link — user clicks to authorize
2. Prompt for region (e.g.

   cn-hangzhou

   ,

   cn-beijing

   ) — user enters their preferred region
3. Prompt for language (e.g.

   zh

   ) — user enters their preferred language

After OAuth setup completes, verify with:

aliyun sts get-caller-identity --profile oauth

⛔ SA-2.12 — DO NOT explicitly handle AK/SK: This skill MUST rely on the aliyun CLI/SDK default credential chain (OAuth / ECS RAM Role / env vars / pre-existing

~/.aliyun/config.json

). The Agent NEVER asks the user to paste AccessKey/Secret/STS-Token values into the chat, NEVER puts raw AK/SK in tool-call arguments or scripts, and NEVER echoes credential values. When credentials are missing, instruct the user to configure them out-of-band (their own terminal/shell profile/RAM role) and only re-verify via

aliyun sts get-caller-identity

. Full remediation flow → references/init-and-credentials.md.

CRITICAL PROHIBITION: NEVER run standalone

appmanager

or

aliyun appmanager login

.

CRITICAL ORDERING RULE: Before scanning any project files, the Agent MUST read

README.md

(or

README

) in the project root. This is ALWAYS the first action in Task 3.

• Quick-start / deploy commands (e.g.

  pip install -r requirements.txt && python main.py

  ,

  npm install && npm start

  )
• Official build/run commands, Docker deploy methods, port number, required environment variables

npm install -g

pip install

go install

pip install && python main.py

npm install && npm start

bash deploy.sh

• README has native method (priority 1/2) → Use it directly as start script core. NEVER ignore README and build from scratch.
• README only has Docker → Check image accessibility (see references/script-templates.md "Docker Image Accessibility Check"). Warn user about China mirror risks.
• README has no deploy info / absent → Agent scans project files independently (only allowed case).

Why README first? Most projects document the exact build/run commands. Auto-detecting from files alone is error-prone.

1. Which region do you want to deploy to?

• Shanghai (cn-shanghai) / Hangzhou (cn-hangzhou) / Beijing (cn-beijing) / Shenzhen (cn-shenzhen) / Guangzhou (cn-guangzhou) / Chengdu (cn-chengdu) / Nanjing (cn-nanjing) / Hong Kong (cn-hongkong)

2. New ECS or existing ECS?

• New ECS (auto-create instance, pay-as-you-go)
• Existing ECS (please provide the instance ID, e.g.

  i-bp1xxxxxxxx

  )

⚠️ REGION PROPAGATION CHECK (MANDATORY): The chosen region MUST be passed verbatim to

appmanager init --region

, written into

config.yaml

common.deployment.regionId

, AND attached as

--region <REGION_ID>

to every subsequent

deploy_toolkit.py {price,deploy,verify}

invocation. Mismatch / omission triggers

InvalidParameter: DeployRegionId is invalid

from the OOS API.

1. Read README.md FIRST — follow Task 3 decision tree
2. If README has no deploy info — scan project structure (Language Detection below)
3. Docker accessibility check — if Docker path selected (see references/script-templates.md)
4. Generate start & stop scripts — following rules below. Start script MUST ALWAYS include zip extraction sequence.
5. Write to config.yaml — under

   common.scripts.start

   and

   common.scripts.stop

   (NEVER top-level

   scripts

   )

• Python:

  [project.scripts]

  in pyproject.toml →

  main.py

  →

  app.py

  →

  manage.py

• Node.js:

  scripts.start

  →

  main

  field →

  index.js

  →

  server.js

• Java:

  find ... -name "*.jar" | head -1

  →

  java -jar

• Go: Pre-compiled binary:

  find ... -type f -perm /111

• PHP:

  composer install --no-dev

  →

  php artisan serve

  or

  php -S

• Docker Compose:

  docker compose up -d

  /

  docker compose down

mkdir -p

unzip -o

cd

command -v unzip &>/dev/null || $PKG_MGR install -y unzip

/root/app.log

/root/app.pid

>>

>

echo $! > /root/app.pid

nohup ... &

nohup ... >> /root/app.log 2>&1 &

[ -f /root/app.pid ] && kill "$(cat /root/app.pid)" 2>/dev/null || true

/root/{app_name}

<< 'EOF'

printf

python3 -c

sleep 3 && cat /root/app.log

exit

ECS instances are bare Linux (typically Alibaba Cloud Linux, RHEL-based, uses

yum

/

dnf

).

MANDATORY: Before deploying, run

deploy_toolkit.py price

. The script outputs the price estimate (with OSS extra-billing reminder) and, when applicable, a risk warning block. The Agent MUST present every flagged item to the user and obtain explicit confirmation BEFORE running

deploy

.

python3 "$SKILL_DIR/scripts/deploy_toolkit.py" price --config .appmanager/config.yaml

• Exit 0 +

  === AGENT_CONFIRM_REQUIRED ===

  : present the complete price + risk warning to the user, confirm item by item.
• Exit 1: price query failed; do NOT proceed to deploy.

Until ALL applicable confirmations are complete, the Agent MUST NOT invoke

deploy_toolkit.py deploy

.

aliyun appmanager <agent|app> deploy --overwrite --output json

STOP after deploy success —

status: success

only means orchestration completed. Agent MUST run Task 6 verification before outputting results.

⛔ MANDATORY FAILURE GATE: After ANY deploy failure (exit 1, timeout, or

ReleaseCancelled

), the Agent MUST run

deploy_toolkit.py verify

IMMEDIATELY — BEFORE any fix attempt, fallback to manual commands, or partial output. Skipping verify after a failure is FORBIDDEN and counts as skill failure.

Semantics of

ReleaseCancelled

: it means the start script on ECS failed or timed out. It does NOT mean "someone cancelled the deploy". The only correct next action: run

deploy_toolkit.py verify

-> read the log -> fix the script -> redeploy.

Known failure patterns: Before ad-hoc troubleshooting, check references/lessons-learned.md for previously identified deployment failure patterns and proven fixes.

1. Run

   deploy_toolkit.py verify

   to fetch

   /root/app.log

   (DO NOT skip).
2. Analyze the log to locate root cause.
3. Fix scripts and redeploy (max 3 attempts).
4. After 3 failures, stop — report the error, but still output console link + cost reminder + delete command.

status: Deployed

does NOT mean the application is running. The Agent MUST run verify and semantically analyze the log.

1. Run

   deploy_toolkit.py verify

   (auto-reads parameters from config.yaml).
2. Agent semantically analyzes the log to decide whether the application actually started successfully.
3. Not running -> diagnose -> fix -> redeploy + verify (max 3 attempts).
4. Only when running is confirmed / user manual action required / 3 attempts failed should the Agent output the final result.

• List/Delete commands
• Config validation
• Config template reference
• Critical notes & pitfalls
• MANDATORY post-deploy output format (console link, cost reminder, usage guide)

Deployment self-check report

📘 Hands-on walk-through with concrete inputs/outputs and edge cases (Python Flask example): see references/tutorial-flask-app.md.

⛔ MANDATORY EXECUTION RULE: The Agent MUST follow this sequence exactly. For steps that specify a script (steps 1, 5, 6), the Agent MUST run the script — NEVER manually replicate the script's logic with individual commands. The Task sections above are REFERENCE ONLY (for understanding what the scripts do internally or as fallback if scripts are missing).