amdev: the Developer CLI¶

amdev is the developer CLI of Module Suite 4.1.0 (Polaris). Developers and coding agents (Cursor, Claude Code, Codex, and others) use it to build Shell Components, AI Views, and Content Scripts outside the browser editors.

amdev is one tool with two modes:

Offline mode is the default. It needs no login and no network. It makes, checks, compiles, and packages a Shell Component or an AI View on your computer, with the copy of the compiler that ships in the kit. You do not need Aether.
Online mode needs a login to a host: Content Server or Module Suite Runtime (MSR). It adds the Module Suite knowledge corpus, the runtime guides, the full Aether checks (build --online), the host lint, the host API catalog, script pull and push, and a local preview of a Shell Component.

amdev does not write the component for you, and it does not start a Generation run. The coding agent, or you, writes the code. amdev also never makes a version active: a person does the last step, in the builder or in the terminal.

When to use each mode¶

Situation	Mode
Your organization has no Aether subscription	Offline
Your computer has no network access to Aether or to the host	Offline
You change a component or a view that a partner installed	Offline (`unpack`, then `check` and `build`)
A coding agent needs the runtime guides, the knowledge corpus, or the Content Script API catalog	Online
You want the full Aether checks before you upload a version	Online (`build --online`)
You change a Content Script on a host	Online (`lint`, `script pull`, `script push`)
You want to see a Shell Component while you edit it	Online (`preview`)

flowchart LR
    Agent["Coding agent or developer"] --> Amdev["amdev"]
    subgraph OfflineMode["Offline mode (default)"]
        Kit["Kit: checks, compiler copy, runtime inputs"]
        Folder["Source Folder"]
        Dist["dist folder: .amver file"]
    end
    subgraph OnlineMode["Online mode (after amdev login)"]
        Host["Content Server or MSR"]
        Aether["Aether"]
    end
    Amdev -->|"new, unpack, check, build"| Kit
    Kit --> Folder
    Kit --> Dist
    Amdev -->|"ticket or OAuth login"| Host
    Host -->|"lint, API catalog, scripts, Aether token"| Amdev
    Amdev -->|"knowledge, guide, build --online"| Aether

In offline mode, everything happens on your computer. In online mode, amdev logs in to the host. The host gives the lint, the API catalog, the script storage, and the Aether token. amdev uses that token for the knowledge corpus, the runtime guides, and the online build. Aether takes no part for a Content Script.

Installation and first run¶

amdev ships as a project ZIP, developer-cli-<version>.zip, on the customer download portal, next to the Module Suite release. Its version is the suite version.

Use the amdev version of your server

Use the same amdev version as your Module Suite server, for example amdev 4.1.0 with Module Suite 4.1.0. amdev 4.1.0 holds the shell runtime v1 and the form runtime v16. A server refuses a version file for a runtime version that it does not have.

To install amdev:

Download developer-cli-<version>.zip for your Module Suite release.
Install Node.js 22 or later. amdev does not run on an older version.
Unzip the file to a folder on your computer, and open a terminal in that folder.
Install the dependencies one time. This step needs a connection to the npm registry. After it, the offline mode works with no network.
```
npm ci --omit=dev
```
Put amdev on the PATH. In the same folder, run:
```
npm install -g .
```
npm adds amdev to its global folder, which is on the PATH (on Windows, %APPDATA%\npm). The command points to this folder, so do not move or delete the folder. If npm cannot write its global folder on Linux or macOS, install Node.js with a version manager, or run the command with sudo.
Open a new terminal and check the installation:
```
amdev --version
```

Without step 5, run node <amdev folder>/bin/amdev.mjs in place of amdev.

A computer with no access to the npm registry

Do steps 1 to 4 on a computer that has access to the npm registry and has the same operating system and processor type (for example Windows x64). Then copy the complete folder, with node_modules, to the other computer. The build packages contain native files for each platform, so a folder installed on another operating system does not work.

To update amdev, unzip the new version, do steps 4 and 5 in the new folder, then delete the old folder. To remove amdev, run:

npm uninstall -g @answer/developer-cli

What the ZIP contains¶

Folder or file	Content
`bin/`, `lib/`	The `amdev` command and its code
`runtimes/`	The compile inputs of each runtime version in the kit: the list of runtime exports and the theme files. `runtimes/index.json` lists the versions.
`examples/`	Two Source Folders: `kpi-card` (a Shell Component) and `request-form` (an AI View)
`skills/`	The agent skill `module-suite-developer`, which `amdev agent setup` installs
`README.md`, `LICENSE.txt`, `THIRD-PARTY-NOTICES.md`	Documents

The ZIP contains no runtime guide, no compiled runtime, no Design Profile CSS, and no Aether source. The runtime guides are online only (amdev guide). For the runtime API, read the Shell Page reference and the AI Form Builder pages.

Commands reference¶

Run amdev --help for the list of commands and amdev <command> --help for the options of one command. Each command description in the help starts with [offline] or [online].

Global options¶

Option	Description	Default
`--json`	Print one JSON object on stdout. Progress text goes to stderr.	Off
`--host <name>`	The host connection that an online command uses, when you have more than one.	The default connection, or the only one
`-V`, `--version`	Print the `amdev` version.
`-h`, `--help`	Print the help.

Offline commands¶

Command	Description
`amdev new <family> <folder>`	Make a new Source Folder with the default files. `<family>` is `shell` or `form`. The folder must be new or empty.
`amdev unpack <file> <folder>`	Make a Source Folder from a downloaded `.amver` file. The folder must be new or empty.
`amdev check <folder>`	Check a Source Folder. Prints one line for each problem.
`amdev build <folder>`	Check, compile, and package a Source Folder into an `.amver` file. With `--online`, Aether checks, compiles, and packages it.
`amdev agent setup`	Install the `amdev` skill for a coding agent.

Options of new, check, and build:

Option	Description	Default
`--runtime <version>`	The runtime version, for example `v1` (shell) or `v16` (form).	`runtimeVersion` in `generation.json`, else the newest runtime of the kit
`--target <host>`	The delivery platform: `content-server` or `script-console` (Module Suite Runtime).	`targetHost` in `generation.json`, else `content-server`
`--recipe <recipe>`	`shell` or `form`, for a folder that holds both `ShellView.vue` and `FormView.vue`. Not on `new`.	Detected from the view file
`--online`	`build` only: send the Source Folder to Aether for the full server checks. Needs a login.	Off

Options of agent setup:

Option	Description	Default
`--target <agent>`	Required. The coding agent: `cursor`, `claude`, `codex`, or `agents-md`.
`--project <folder>`	The project folder of the agent.	The current folder

Online commands¶

Command	Description
`amdev login <url>`	Log in to a host. A person must run it in their own terminal.
`amdev logout`	Remove the selected host connection.
`amdev status`	Show the host connection, and whether Aether and the knowledge are available.
`amdev knowledge search <query>`	Search the approved Module Suite knowledge corpus.
`amdev knowledge get <itemId>`	Read a knowledge item, or some of its sections.
`amdev knowledge follow <itemId>`	List the items related to a knowledge item.
`amdev guide <family>`	Get the runtime guide of `shell` or `form` (`AGENT.md`, skills, design notes).
`amdev api services`	List the Content Script API services of the host.
`amdev api service <name>`	Describe one API service.
`amdev api object <type>`	Describe one API object type.
`amdev lint <file>`	Lint a Content Script with the compiler of the host.
`amdev script pull <ref> <file>`	Read a script from the host into a local file.
`amdev script push <file> [ref]`	Store the file as a new version on the host. A person must type `yes`.
`amdev build <folder> --online`	Build with all the Aether checks. See Build with the Aether checks.
`amdev preview <folder>`	Show a Shell Component in a local page with the runtime of the host. It builds again when a file changes.

Options of login:

Option	Description	Default
`--type <type>`	Required. The host type: `content-server` or `script-console` (Module Suite Runtime).
`--role <role>`	Required. The host role: `development`, `test`, or `production`.	No default
`--name <name>`	The name of the host connection.	The host name of the URL
`--auth <method>`	Content Server only: `password` or `otds`.	`password`
`--user <name>`	Content Server user name for the password login.	Asked at the terminal
`--otds-url <url>`	OTDS base URL, without `/otdsws`. Required with `--auth otds`.
`--otds-client-id <id>`	OTDS OAuth client id. Required with `--auth otds`.
`--default`	Make this the default host connection.	The first login becomes the default

Options of logout:

Option	Description	Default
`--all`	Remove all host connections.	Off: removes the connection of `--host`, else the default

Options of knowledge search:

Option	Description	Default
`--kinds <list>`	Item kinds, separated by commas: `concept`, `reference`, `guide`, `index`, `example`.	All kinds
`--tags <list>`	Tags, separated by commas.	No filter
`--limit <n>`	At most this many items, from 1 to 50.	Set by Aether

Options of knowledge get:

Option	Description	Default
`--projection <type>`	`outline`, `section`, `sections`, `text-only`, `examples-only`, or `full`.	`outline`; `section` with `--section`; `sections` with `--sections`
`--section <id>`	One section id. Required with `--projection section`.
`--sections <list>`	Section ids, separated by commas. Required with `--projection sections`.
`--max-blocks <n>`	At most this many blocks.	40, except for `outline`

Options of knowledge follow:

Option	Description	Default
`--depth <n>`	The relationship depth, from 1 to 3.	Set by Aether
`--limit <n>`	At most this many relationships.	Set by Aether

Options of guide:

Option	Description	Default
`--runtime <version>`	The runtime version of the guide.	The newest runtime of the family in the kit
`--out <folder>`	Write the guide files to this folder. Without it, `amdev` lists the file paths.

Options of lint:

Option	Description	Default
`--mode <mode>`	The validation mode on Content Server.	`ContentScript`

Options of script pull:

Option	Description	Default
`--force`	Replace the local file if it exists.	Off: the command stops if the file exists

script push has no options of its own. The optional [ref] must be the reference of the pull; the default is the reference of the pull.

Options of preview:

Option	Description	Default
`--runtime <version>`	The runtime version.	`runtimeVersion` in `generation.json`, else the newest runtime of the kit
`--port <n>`	The local port, from 1024 to 65535.	The first free port of 53690 to 53699
`--props <file>`	A JSON file with the input values of the component.	The defaults of `inputSchema`
`--profile <id>`	The Design Profile, for example `jato` or `portal`.	`designProfile` in `component.json`
`--theme <theme>`	The colour mode: `light` or `dark`.	`light`
`--locale <code>`	The locale, from `locales.json`.	The default locale
`--no-open`	Do not open the browser.	The browser opens

Output and exit codes¶

amdev writes no colours, spinners, or progress bars. In text mode it prints the result on stdout, and warnings and diagnostics on stderr. A diagnostic line has the form <file>: <severity> <code> <message>.

With --json, amdev prints one JSON object on stdout at the end, and progress text on stderr. This is the mode for a coding agent:

{
  "ok": true,
  "command": "build",
  "mode": "offline",
  "result": {
    "file": "/home/dev/work/kpi-card/dist/kit.kpi-card-20261029-153000.amver",
    "family": "shell",
    "runtimeVersion": "v1",
    "targetHost": "content-server",
    "handOff": "Open the builder, upload this file, check the preview, authorize the metadata, then confirm."
  },
  "diagnostics": [],
  "warnings": ["Server checks not done: run \"amdev build --online\" for the full Aether checks."],
  "error": null
}

When a command fails, ok is false, result is null, and error has a code, a message, and sometimes details. The exit codes do not change between releases:

Code	Meaning
0	Success
1	Diagnostics or a validation failure
2	A usage error or an invalid request
3	Not logged in
4	The host or Aether is not available, or the network is blocked
5	A confirmation is refused or not possible
6	A version conflict, or a script reserved by another user
7	Forbidden

Offline workflow¶

Each component or view has its own folder, the Source Folder. You start it with new or unpack, edit its files, run check, and run build. The build writes an .amver version file that a person uploads in the builder.

flowchart TD
    NewCmd["amdev new shell or form"] --> Folder["Source Folder"]
    Download["Download a version from the builder"] --> Unpack["amdev unpack"]
    Unpack --> Folder
    Folder --> Edit["Agent or developer edits the files"]
    Edit --> Check["amdev check"]
    Check -->|"errors"| Edit
    Check -->|"no errors"| Build["amdev build, or build --online"]
    Build --> Amver["dist folder: .amver file"]
    Amver --> Upload["Person uploads the file in the builder"]
    Upload --> Preview["Preview in the builder"]
    Preview -->|"not correct: cancel"| Edit
    Preview --> Authorize["Authorize the metadata"]
    Authorize --> Confirm["Confirm the deploy or the upload"]
    Confirm --> Active["New version, active at once"]

Nothing is stored on the host before the person confirms in the builder.

Start a Source Folder¶

Shell ComponentAI ViewFrom an existing version

amdev new shell ~/work/my-component

amdev new form ~/work/my-form

Download the version file from the builder, then run:

amdev unpack ~/work/download.amver ~/work/my-component

unpack detects the family from the view file, removes the fields that the host owns from component.json (authorizationStatus, bundleUrl, stylesUrl, versionId), and writes generation.json with the runtime version and the delivery platform of the version. If the version file lacks a required file, amdev warns you; add the file before you build.

new writes the default files of the family and a generation.json with the runtime version and the delivery platform. Use --runtime and --target to choose other values.

Source Folder files¶

A Shell Component has these files:

File	Required	Content
`ShellView.vue`	Yes	The component (a Vue single-file component with `<script setup>`, plain JavaScript)
`source.css`	Yes, can be empty	Your CSS
`component.json`	Yes	The `key`, `inputSchema`, capabilities, and the other metadata
`locales.json`	No	The texts: `{"defaultLocale":"en","locales":{"en":{"key":"text"}}}`
`generation.json`	No	The runtime version and the delivery platform

An AI View has these files:

File	Required	Content
`FormView.vue`	Yes	The view (a Vue single-file component with `<script setup>`, plain JavaScript)
`source.css`	Yes, can be empty	Your CSS
`fieldset.json`	Yes	The fields
`rules.json`	Yes	The rules
`dataSources.json`	Yes	The data sources (a JSON array)
`locales.json`	Yes	The texts
`generation.json`	No	The runtime version, the delivery platform, and the Design Profile

Follow these rules:

Import only from vue and from the runtime package: @amshell/runtime for a Shell Component, @aifb/runtime for an AI View. The runtime package also gives the UI kit and the icons.
Put all other code in the .vue file.
For each t('key') in ShellView.vue, add the text of the key to the default locale.
Do not write authorizationStatus in component.json. The builder sets it when you authorize the metadata.
Keep one view file in each folder. If a folder holds both ShellView.vue and FormView.vue, add --recipe shell or --recipe form.

For Module Suite Runtime, set "targetHost": "script-console" in generation.json, or add --target script-console to the command. The default is content-server. See Choosing the Delivery platform.

For the Design Profile, set designProfile in component.json (Shell Component) or in generation.json (AI View), for example jato, portal, or studio. If you do not set it, an existing component or view keeps its current profile, and a new one gets the default profile of the server. See Design Profile.

The kpi-card example in examples/ has this component.json:

{
  "key": "kit.kpi-card",
  "inputSchema": {
    "type": "object",
    "properties": {
      "count": { "type": "number", "default": 0 }
    }
  },
  "capabilities": { "notifications": true },
  "requiredPermissions": [],
  "sharedState": {},
  "events": { "publishes": [], "subscribes": [] },
  "dataSources": [],
  "designProfile": "jato"
}

Check¶

amdev check ~/work/my-component

The check reads the files of the family, checks that the required files exist and that each JSON file parses, checks the imports against the exports of the runtime version, and checks component.json and locales.json (Shell Component) or fieldset.json and dataSources.json (AI View). Correct each error and run the command again. A warning does not stop the build. The error codes are listed in Troubleshooting.

Build¶

OfflineOnline

amdev build ~/work/my-component

The offline build runs the checks of amdev check, compiles the view with the copy of the compiler in the kit, and packages the result. It always warns that the server checks were not done.

amdev build ~/work/my-component --online

The online build needs a login. Aether runs all its checks, compiles, and packages the Source Folder. See Build with the Aether checks.

Both builds write the version file to the dist folder of the Source Folder. The file name is <name>-<yyyyMMdd-HHmmss>.amver, where the name is the component key of a Shell Component, or the folder name of an AI View. For example: ~/work/my-component/dist/kit.kpi-card-20261029-153000.amver.

The version file holds the source files, the compiled bundle.js and styles.css, and a generation.json that records builtBy: "amdev", the amdev version, the build mode, and the runtime version. The hosts accept a version file of at most 10 MB.

Upload and confirm in the builder¶

The hosts keep no inactive versions, so a person uploads, reviews, and confirms each version:

Open the Component AI Builder for a Shell Component, or the AI Form Builder for an AI View.
Load the version file. In the Component AI Builder, use the version file upload. In the AI Form Builder, open History and upload the version file.
Examine the preview. For an AI View, also examine the changes to the Form Template.
Examine the metadata: the key, the inputs, the capabilities, and the permissions. Authorize the metadata.
Confirm the deploy or the upload.

If the result is not correct, cancel, edit the Source Folder, and build again. When you confirm, the new version can become active at once. To undo a version, restore the previous version in the builder.

Online mode¶

Log in¶

You log in yourself, in your own terminal. A coding agent cannot log in: when amdev has no person at the terminal, login stops with login_requires_person and prints the command to run.

Each login has a role: development, test, or production. There is no default. Use a development or test host for work with a coding agent.

Content Server (password)Content Server (OTDS)Module Suite Runtime

amdev login https://cs.example.com/otcs/cs.exe --type content-server --role test

The URL is the Content Server CGI URL. amdev asks for the user name (unless you give --user) and the password. The password is used once and never stored.

amdev login https://cs.example.com/otcs/cs.exe --type content-server --role test \
  --auth otds --otds-url https://otds.example.com --otds-client-id amdev

Use this login when your users sign in to Content Server through OTDS single sign-on (an identity provider, Kerberos, or multi-factor authentication). The password login does not work for these users. Your administrator gives you the OTDS address and the client id. See Content Server with OTDS.

amdev login https://msr.example.com --type script-console --role test

The URL is the MSR base URL. amdev registers itself one time with the MSR authorization server and asks only for the scopes openid script:read script:write.

For OTDS and MSR, amdev opens your browser at the login page. If the browser does not open, open the address that amdev prints. The login uses the first free local port of 53682, 53683, and 53684.

On Content Server, only a user who can add items to the Content Script Volume, or modify a Content Script, gets the Aether access.

Manage the logins with these commands:

amdev status                 # host, role, user, and whether Aether and the knowledge are available
amdev status --host cs-test  # the same for another connection
amdev logout                 # remove the selected connection
amdev logout --all           # remove all connections

Content Server with OTDS¶

An OTDS administrator sets up the OAuth client one time:

In OTDS Admin, open OAuth Clients and add a client:

Field	Value	Why
Client ID	`amdev` (or another id)	The users give it with `--otds-client-id`.
Confidential	Not selected (no secret)	`amdev` runs on the computer of the user and cannot keep a secret. PKCE (S256) protects the login.
Redirect URLs	`http://127.0.0.1:53682/callback`, `http://127.0.0.1:53683/callback`, `http://127.0.0.1:53684/callback`	`amdev` receives the login on the first free port of the three. Add all three.
Refresh token	Allowed	`amdev` renews the Content Server ticket with it, with no new login.

amdev asks for no scope.

Make sure that Content Server uses this OTDS server. OTDS can be on a different host than Content Server.
Make sure that the partition of the users has access to the Content Server resource.
Make sure that the user name mapping of the Content Server resource gives the Content Server login name.
Give the users the OTDS address and the client id.

Give --otds-url without /otdsws. You sign in on the OTDS page as usual; amdev never sees your password. amdev exchanges the OTDS access token for a Content Server ticket, and keeps the ticket and the refresh token, not the access token. When Content Server refuses an expired ticket, amdev gets a new ticket with the refresh token, with no browser, and repeats the command one time. When OTDS refuses the refresh token, log in again.

Knowledge corpus and runtime guides¶

The knowledge corpus is the approved Module Suite knowledge that Aether uses to ground a Generation run. In online mode, a developer or an agent can search and read it:

amdev knowledge search "shell page regions"
amdev knowledge search "picker field" --kinds reference,example --limit 5
amdev knowledge get <itemId>
amdev knowledge get <itemId> --sections <a,b>
amdev knowledge follow <itemId> --depth 2

knowledge search prints one line for each item (<itemId> <title>), and the matched section when there is one. knowledge get without options returns the outline of the item; read the outline first, then only the sections you need.

The runtime guide of a family is a set of files: AGENT.md, skills, and design notes. Read AGENT.md first.

amdev guide shell --out ~/work/guide/shell
amdev guide form --runtime v16 --out ~/work/guide/form

Build with the Aether checks¶

amdev build ~/work/my-component --online

build --online does these steps:

It runs the offline checks. If there is an error, it stops.
It checks that the host installs the runtime version of the Source Folder. If the host does not install it, the build stops with runtime_not_installed. Module Suite Runtime cannot tell amdev which runtimes it installs, so amdev warns that the runtime was not checked; the upload checks it.
It sends the files of the Source Folder to Aether for validation. Aether returns its diagnostics and warnings.
For a Shell Component for Module Suite Runtime, Aether can check the REST calls of the component only when it holds one MSR REST catalog for your tenant. Otherwise amdev warns "REST catalog check skipped".
It downloads the package from Aether, checks its size and its contents, and writes it to the dist folder.

Then upload and confirm the version file in the builder, as for an offline build. Read the warnings of each online build.

Lint and the API catalog¶

Lint and the API catalog come from the host, so they match the Content Script API of the server you work with.

amdev lint ~/work/report.groovy
amdev api services
amdev api service docman
amdev api object CSNode

A lint finding has the form <file>:<line>:<column> <severity> <message>. The editor runs the same validation; see Code validation.

Pull and push a Content Script¶

sequenceDiagram
    participant Agent as Coding agent
    participant Person as Person at the terminal
    participant Amdev as amdev
    participant Host as Content Server or MSR
    Agent->>Amdev: script pull ref file
    Amdev->>Host: Read the script
    Host-->>Amdev: Source and version
    Amdev-->>Agent: file and file.amdev.json
    Agent->>Amdev: Edit, then amdev lint file
    Person->>Amdev: script push file
    Amdev->>Host: Lint with the host compiler
    Amdev->>Host: Read the current version
    Amdev-->>Person: Host, script, lines added and removed
    alt Script changed after the pull
        Amdev-->>Person: version_conflict, nothing written
    else Script unchanged
        Person->>Amdev: Types yes, and the host name on production
        Amdev->>Host: Write with the version of the pull
        alt Script changed in the meantime
            Host-->>Amdev: Write refused
        else
            Host-->>Amdev: New version, active at once
        end
    end

Pull the script:
```
amdev script pull 12345 ~/work/report.groovy
```
On Content Server, the reference is a node id or a nickname. On Module Suite Runtime, it is a path below the script root, for example reports/monthly.groovy. amdev writes the script to the file, and writes report.groovy.amdev.json next to it with the host, the reference, and the version of the pull. If the file exists, add --force.
Edit the file, and lint it with amdev lint.
Push the file, in your own terminal:
```
amdev script push ~/work/report.groovy
```
amdev uses the host and the reference of the pull. It lints the file with the host compiler and stops on a lint error. It shows the host, the script, and the number of lines added and removed, then asks you to type yes. On a host with the role production, you must also type the name of the host connection.
If the script changed on the host after your pull, amdev stops with version_conflict, and the host also refuses the write. Pull again, then apply your change again. On Content Server, a script reserved by another user gives script_reserved.

A push stores a new version, and the new version is active at once. To go back, use the version list of the script; see Versions.

A push needs a person

When there is no person at the terminal, script push stops with confirmation_required and writes nothing. A coding agent cannot push a script.

Preview a Shell Component¶

amdev preview ~/work/my-component
amdev preview ~/work/my-component --props props.json --profile portal --theme dark --locale it

amdev opens a local page at http://127.0.0.1:53690/ (or the next free port up to 53699) that shows the component. When you save a file, amdev builds again and the page shows the new build. Press Ctrl+C to stop. The page keeps the theme, the profile, and the locale in its address, for example http://127.0.0.1:53690/?theme=dark&profile=portal.

The preview uses the preview page of the Component AI Builder and the shell runtime of your host, so the components, the runtime version, and the Design Profiles are those of your host. amdev ships no runtime.
amdev gets these files from the host and serves them from its local address. The local page answers only on 127.0.0.1, and your login never goes to the browser.
REST calls, notifications, dialogs, and events have stand-ins. The preview shows the look and the layout, not the data of your server.
The preview is not the review. Upload the version file in the builder, check the preview there, and confirm.
The preview is for Shell Components only. On Content Server, it needs Module Suite 4.1 or later.

Use amdev from a coding agent¶

The coding agent writes the code and runs amdev to check, build, and read the knowledge. You log in, confirm versions in the builder, and push scripts.

In your project folder, install the skill one time:
CursorClaude CodeCodex and other agents
amdev agent setup --target cursor
Writes .cursor/skills/module-suite-developer/SKILL.md.
amdev agent setup --target claude
Writes .claude/skills/module-suite-developer/SKILL.md.
amdev agent setup --target codex
--target codex and --target agents-md write a section of AGENTS.md, between  and . The rest of the file does not change. A second run replaces the section.
The skill contains the full path of this amdev folder (node "<folder>/bin/amdev.mjs"), not amdev, because the shell of an agent often has a different PATH. If you move or update amdev, run the command again.
Log in yourself, in your own terminal.
Allow the network of the agent: the address of your host and the address of Aether. Also allow the amdev credentials folder (~/.amdev/, or %APPDATA%\amdev\ on Windows). The offline commands need no permission.
- Cursor: allow the addresses for the agent terminal, or run the command outside the sandbox.
- Claude Code: allow the addresses and the folder in the sandbox settings.
- Codex: turn on the network access of the sandbox, or run the command outside the sandbox.
The agent adds --json and reads the result object. An agent with a browser tool can run amdev preview <folder> --no-open --json in the background, open the result.url, wait until the page <body> has data-state="rendered", and take a screenshot. data-state="error" means that the folder has errors, and the page lists them.

What the skill gives an agent¶

The module-suite-developer skill tells the agent when to use amdev (a Shell Component, an AI View, or a Content Script for Content Server or Module Suite Runtime) and how:

Offline, always available: start with new or unpack, run check --json after each change and correct every error, then build --json.
Online, when you are logged in: run status --json; read the runtime guide (guide shell --out .amdev-guide/shell, then AGENT.md) and search the knowledge before it writes code, one search for each question; read the host API catalog for Content Script questions; lint each Content Script; build with --online before the hand-off; pull a script before it changes it; use preview to see a Shell Component.
Rules: the agent cannot log in and waits for you on not_logged_in or login_requires_person; it does not run script push; after a build it gives you the .amver path and the hand-off text; it reports the build warnings; it treats forbidden as a limit, not as an error to work around; on network_blocked or credentials_blocked it asks you to allow the address or the path; it does not read hosts.json and does not call the host or Aether directly.

Files that amdev reads and writes¶

File	Written by	Content
`~/.amdev/hosts.json` (Windows: `%APPDATA%\amdev\hosts.json`)	`login`, `logout`, and renewed logins	The host connections: type, URL, role, user, and the Content Server ticket, the OTDS refresh token, or the MSR client id and refresh token. No password, no tenant client secret, and no Aether token.
Source Folder files	`new`, `unpack`; read by `check`, `build`, `preview`	See Source Folder files
`<Source Folder>/dist/<name>-<yyyyMMdd-HHmmss>.amver`	`build`	The version file to upload in the builder
`<file>` and `<file>.amdev.json`	`script pull`, `script push`	The script, and the host, reference, and version of the pull (and the time of the last push)
Guide files in the `--out` folder	`guide --out`	`AGENT.md`, skills, and design notes
`.cursor/skills/module-suite-developer/SKILL.md`, `.claude/skills/module-suite-developer/SKILL.md`, or `AGENTS.md`	`agent setup`	The agent skill

Set the environment variable AMDEV_HOME to keep hosts.json in another folder. On Linux and macOS, amdev writes the folder with mode 0700 and the file with mode 0600. On Windows, the user profile folder is readable only by its user by default. If hosts.json is not valid JSON, delete it and log in again.

Network settings¶

Environment variable	Use
`HTTPS_PROXY`, `HTTP_PROXY`	The proxy for the requests to the host, OTDS, and Aether. Set them before you run `amdev`.
`NODE_EXTRA_CA_CERTS`	The certificate file of your company certificate authority.
`AMDEV_HOME`	Another folder for `hosts.json`.

Security¶

amdev keeps the credentials short-lived and on your computer only:

The Content Server password is used once and never stored. With OTDS and MSR, you sign in on the login page; amdev never sees your password.
amdev never stores a tenant client secret or an Aether token on disk. The host gives the Aether token after your login.
The Aether token is the shared tenant token of the host, the same token that the browser editors receive. It is in the memory of each amdev process and in its requests, so the agent can see it. Treat it as a tenant credential, not as a personal one.
When Aether refuses the token, amdev asks the host for a new token one time. The new token replaces the token of the browser editors on that host too.
hosts.json holds a Content Server ticket or a refresh token. The agent runs as your user, so it can read the file.
On Module Suite Runtime, amdev asks only for the scopes openid script:read script:write.
The preview page answers only on 127.0.0.1, and your login never goes to the browser.

The confirmation is not a security control

The yes prompt of script push, the host name prompt on a production host, and the upload in the builder make sure that a person sees each change. They do not protect the host from the agent: the agent runs as the same user as you, can read your login, and can call the host directly. The controls are the host permissions of your user, least-privilege scopes, short-lived credentials, and a development or test host. Do not give a coding agent a login to a production host, and run amdev logout --all when you stop.

Troubleshooting¶

Check errors¶

Code	Correction
`missing_file`	Add the file. `source.css` can be empty.
`invalid_json`	Correct the JSON syntax of the file.
`shell_import_not_allowed`, `form_import_not_allowed`	Import only from `vue` and the runtime package.
`unsupported_runtime_import`	The runtime version does not export this name. Correct the name, or select another runtime version.
`component_key_required`	Set a `key` in `component.json`, for example `customer.orders`.
`input_schema_required`, `input_schema_properties_required`	Set `"inputSchema": {"type":"object","properties":{}}`, with one property for each input.
`capabilities_must_be_map`	Write the capabilities as a map, for example `{"restClient": true}`.
`publication_owned_field`	Remove `authorizationStatus` from `component.json`.
`locales_invalid`	Make sure `locales` contains the `defaultLocale`.
`locale_default_missing`	Add the text of each key to the default locale.
`invalid_fieldset`	Each field needs a unique `name` and a `type`; a `SET` needs fields; a picker field must be `INTEGER`; `multiplicity` must be 1 or more.
`invalid_datasources`	Make `dataSources.json` a JSON array.
`archive_too_large`, `render_file_too_large`, `render_total_too_large`	Make the component smaller. The limits are 10 MB for the version file, 16 MB for each file, and 20 MB for `bundle.js` and `styles.css` together.

Command errors¶

These are the values of error.code with --json.

Code	Correction
`invalid_request`	Correct the command. Run `amdev <command> --help`.
`validation_failed`	Correct the diagnostics and run the command again.
`runtime_not_installed`	Select a runtime version that the host installs, with `--runtime`.
`file_too_large`	Make the component smaller.
`not_logged_in`	Log in again. With more than one connection, add `--host <name>`.
`login_requires_person`	Run the printed login command yourself, in your own terminal.
`credentials_blocked`	Allow the `amdev` folder in the sandbox of the agent, or run the command outside the sandbox.
`network_blocked`	Allow the printed address in the sandbox of the agent, or run the command outside the sandbox.
`host_unavailable`, `aether_unavailable`	Make sure that the server runs and that you can reach it.
`forbidden`	Your user cannot do this. Ask your administrator.
`confirmation_required`, `confirmation_refused`	Run the command yourself, in your own terminal, and type the answer.
`version_conflict`	The script changed on the host. Pull it again.
`script_reserved`	Another user reserved the script. Ask that user to unreserve it.

You see	Cause	Correction
`invalid_client_id` on the OTDS page	This OTDS server has no client with this id.	Check `--otds-url` (the OTDS server of Content Server) and `--otds-client-id`.
An OTDS error about `redirect_uri`	The redirect URLs of the client are not correct.	Add the three redirect URLs, with no `/` at the end.
`The token request failed (HTTP 400 or 401, invalid_client)`	The client is confidential.	Clear Confidential on the client.
`Content Server did not accept the OTDS login (HTTP 401)`	Content Server uses a different OTDS server, or the partition of the user has no access to the Content Server resource.	Do steps 2 and 3 of the OTDS set-up.
`Unable to locate user with name …`	The user name mapping of the Content Server resource gives a name that Content Server does not know.	Do step 4 of the OTDS set-up.
`The login has expired` after some time	OTDS refused the refresh token.	Allow refresh tokens on the client, then log in again.