The command line and AI agents

axm is the app's command line. It uses the same engine as the desktop app and reads and writes the same *.axm.json files. Anything you can build in the app, you can build with axm, and the results are identical.

The Windows installer puts axm next to the app and adds it to your PATH, so it works in any new terminal.

A first session

axm templates
axm new motor.axm.json --template overhung-pulley
axm solve motor.axm.json
axm sweep motor.axm.json supports.B2.position --from 200mm --to 260mm --steps 4
axm report motor.axm.json --pdf

• axm templates lists the examples, the same as the app's start screen; axm templates --own lists your own templates (File › Save as template in the app), and axm new <file> --template "<name>" starts from one.
• axm new makes a project file, from a template or blank.
• axm solve prints the results and the checks. Add --detail for per-element bearing results, --json for machine-readable output.
• axm sweep solves across a range of one parameter and tabulates the key results. For the example above, moving the right bearing from 200 to 260 mm raises the left bearing's life from 249 249 h to 387 188 h. Every row fails a check, though: the 17 mm wide bearing no longer sits on its Ø35 mm seat (235 to 260 mm), so a real change moves the seat with the bearing.
• axm report writes the calculation report as HTML, or as PDF with --pdf.

Edit with commands such as axm section add, axm support update, axm load add, axm bearing add and axm set, or several changes at once with axm apply. Every element module has its own command: axm gear, axm bolt, axm fit, axm spring and so on. axm --help lists them all, and axm <command> --help explains one.

In a terminal, the text output is coloured: PASS green, FAIL red, warnings yellow, headings bold. The words stay, so nothing depends on seeing the colour, and output sent to a file, a pipe or --json is always plain. --color never turns colour off, --color always keeps it in a pipe; the NO_COLOR and FORCE_COLOR environment variables do the same for every command. A solve or search that takes more than a second shows a progress line on the terminal, which disappears when it is done.

Arguments accept units: 120mm, 3kN, 49.4Nm, 2in. Without a unit, a value is read in its field's own unit: mm, N, N·mm for a shaft load's torque, but N·m for a gear pair's torque. --units imperial shows the text output and reports in US customary units; JSON output is always metric. See Units and number entry.

Live editing with the desktop app

When the desktop app has a project file open, it watches the file. A change made by axm or by an agent appears on screen at once, with its results. Your own edits in the app are saved to the file as you make them. The file chip in the top bar shows a dot while the file is watched.

If the file changes before an edit of yours is saved (the disk was full, or the change came first), the app shows the file as it is now and keeps your edit one Undo away, and says so. Leaving the project, or closing the window, asks about that edit first.

So you can keep the app open beside a terminal or an agent and watch the design change.

AI agents

axm is built to be driven by AI agents such as Claude Code and Codex. Agents should always pass --json, read the ok field and follow the hint in an error.

The agent's reference is the guide built into axm:

axm guide                  # the core rules and an index of topics
axm guide bearings         # one topic, with every field, unit and default
axm guide gears bolts      # several topics
axm guide --all            # the whole guide

To set up an agent in a project folder:

axm init-agent

This installs a skill for Claude Code and a section for Codex that hold the guide's core. The agent then reads topics as it needs them.

Agents can also use axm as a Model Context Protocol server, which offers the same operations as tools:

claude mcp add axomek -- axm mcp
codex mcp add axomek -- axm mcp

The Assistant in the app

The Assistant button in the top bar (Ctrl+Shift+A) opens a conversation with Claude about the open project, in the web app and in the desktop app. Ask about the results ("Why is the left bearing's life so short?") or ask for a change ("Add a 6208 at the right support"). The assistant reads the project and its results, and changes it with the same editing commands as axm apply; each change it makes is one undo step, like your own.

On a wide window the assistant sits below the results, in the results column, so the drawing and the verdict stay in view while it works; it collapses to its message line and can have a column of its own on very wide screens (see The assistant). After a reply that changed the project, it lists what changed with the values before and after, as axm diff compares the project before and after the reply: the inputs ("S2 Ø 35 → 40 mm"), the checks that flipped and the results that moved ("BR1 life 60,200 → 48,900 h"). Each line selects its item, and the results that moved are marked for a moment.

The assistant runs with your Axomek account: sign in first. Your messages go through the Axomek account service to the Anthropic API. Each account has a daily number of requests, which resets at midnight UTC; one answer can take several. In the desktop app you can use your own Anthropic API key instead: set ANTHROPIC_API_KEY, or save a key in the panel. When there is one, the desktop app sends your messages with it, straight to the Anthropic API, rather than with your account. A saved key is kept in your user config folder and sent only to the Anthropic API. The line under the message box says which is in use.

Agents in a terminal, such as Claude Code and Codex, work on projects through the axm command line and its MCP server (above), which also need you to sign in: run axm login once on that computer and agents there work with your sign-in. An access key is only for axm where nobody can sign in, such as an agent in the cloud (Settings › Account › Offline computers and automated use). See Privacy choices for what the assistant sends.

More from the command line

axm solve --strict exits with code 4 when a check fails, which makes it useful in scripts and build pipelines. axm check does the same for many files at once: axm check "designs/**/*.axm.json" solves every project below designs, prints one line per file (status, checks passed, worst utilisation) and fails the build if any check fails or any file cannot be solved. A build server without a browser can sign in with an access key in AXM_API_KEY; see axm guide account.

Related

• Tutorial: checking designs in CI
• Tutorial: comparing two designs
• What Axomek does
• Units and number entry
• Reports and export
• Privacy choices