Ae System

ae-system

Use the system domain for Agent system administration:

ae-cli system +<command> [options]
ae-cli system <resource> <action> [options]

Mandatory Rules

• These commands are only for users whose Agent role is root or agent_admin.
• The te-agent /api/admin/** and /api/cli/channel/v1/** endpoints are the final authorization boundaries. A member receives a permission error (HTTP 403). Do not retry login or attempt a different endpoint after a 403.
• Run ae-cli auth login --host <host> before using this domain. System administration requires a valid user CLI-token session; sandbox identity headers are not an authorization substitute.
• +npm-install is the exception that must also run inside a Linux te-agent sandbox because it packages the installed Linux files. It still requires the logged-in user to be root or agent_admin.
• Discover real IDs with a list command before any update or delete. Never guess a user, sandbox, model, quota rule, or channel ID.
• Before every write, run --dry-run, show the target and effect, and obtain explicit user confirmation. The CLI itself prompts only for high-risk-write; --yes can bypass that prompt and is not a security boundary.
• Use --dry-run to inspect method, path, query, and redacted body without executing.
• JSON inputs accept inline JSON, @file, or - for stdin. Prefer @file for channel credentials and other sensitive values.
• Successful output is JSON by default. Use --format table only when a human-readable table is more useful.
• After each command, check stderr and _notice.host_compat. If present, show the version warning and its update commands before the business result.
• Do not treat an absent ae-cli command as proof that an HTTP endpoint is unreachable. An Agent with Bash/network access can construct requests directly; server authentication, role checks, company isolation, and resource ownership are the actual controls.
• Do not call DELETE /api/admin/members?openId=... or /api/internal/sandboxes/** through ad-hoc HTTP. They are intentionally excluded from this Skill because other systems own those integration contracts.

Command Groups

Members

Examples:

ae-cli system +list-members --status enabled --page 1 --page-size 20

ae-cli system +add-members \
  --members '[{"openId":"ou_x","loginName":"alice","displayName":"Alice"}]' \
  --create-sandbox true

ae-cli system +set-member-role --user-id <user-id> --role agent_admin

+list-members filters:

• --q: login/display name search.
• --status: all | enabled | disabled.
• --page, --page-size: page size is 1-100.
• --all: return all matches.
• --sort-field periodUsedAmount, --sort-dir asc|desc: central usage sort.

+add-members --members schema:

[
  {
    "openId": "required",
    "loginName": "optional",
    "displayName": "optional"
  }
]

Optional flags are --rule-id and --create-sandbox true|false.

Sandboxes

Examples:

ae-cli system +batch-create-sandboxes \
  --user-ids '["<user-id-1>","<user-id-2>"]' \
  --description "Data team"

ae-cli system +set-sandbox-enabled --id <sandbox-id> --enabled true
ae-cli system +bind-sandbox-user --id <sandbox-id> --user-id <user-id>

Use Agent database user IDs from +list-members, not AE openIds, for sandbox commands.

Shared Sandbox Tools

Uploaded tools are registered for the current company with enabled=false. Upload does not activate the tool in any running sandbox. Review and enable/activate it through sandbox tool management after upload.

For activate/deactivate/status operations:

ae-cli system +activate-sandbox-tools \
  --target-mode selected \
  --sandbox-ids '["<sandbox-id>"]' \
  --tool-ids '["<tool-id>"]'

• --target-mode selected requires 1-50 --sandbox-ids; all-running forbids them.
• --tool-ids contains 1-20 real IDs from +list-sandbox-tools.
• --command-names-by-tool-id optionally limits an operation to named commands.
• --expected-tool-snapshots-by-id carries the version/package/command snapshot returned by the server for optimistic concurrency checks.
• JSON maps accept inline JSON, @file, or stdin. Use dry-run and user confirmation before distribution changes.

Preferred npm Flow

Run this inside the target Linux te-agent sandbox:

ae-cli auth login --host <host>
ae-cli system +npm-install --package eslint@9.32.0

For a scoped package or a custom shared-tool identifier:

ae-cli system +npm-install \
  --package @scope/example-cli@1.2.3 \
  --name example-cli

Requirements and behavior:

• --package must be an exact registry package version. Tags, ranges, URLs, Git sources, npm aliases, and local paths are rejected.
• The installed package must expose at least one package.json bin entry. Each bin becomes one tool command.
• The default tool name is the unscoped package name. Use --name only when a different valid lowercase tool identifier is required.
• npm lifecycle scripts are disabled with --ignore-scripts by default. Use --allow-scripts true only after reviewing and trusting the package and all transitive dependencies.
• The command calls the admin upload-policy endpoint before starting npm. A disabled feature, expired session, or non-admin role fails before installation.