Skip to content

How-To Guides

See preview, apply and review before applying these recipes.

Task-oriented recipes for common axm-anvil move workflows. The dedicated axm-anvil CLI exposes a single move command, which accepts positional (FROM TO SYMBOLS) or flag (--from-file/--to-file/--symbols) form; see the CLI Reference for the full option list. rename and extract are available via MCP (anvil_rename, anvil_extract) and the axm dispatcher — see Use via MCP.

Preview a move before touching the disk

Bash
axm-anvil move src/mylib/models.py src/mylib/services.py UserService --dry-run

The printed plan lists moved symbols, copied imports/constants, caller rewrites, and any warnings — nothing is written.

Rename a symbol while moving it

Bash
axm-anvil move src/mylib/models.py src/mylib/services.py \
    UserService --rename '{"UserService": "AccountService"}'

The moved definition, supported references, literal exports and supported string annotations in moved blocks are rewritten. Review limits. Incompatible with --reexport.

Control where the moved code lands

Bash
axm-anvil move src/mylib/a.py src/mylib/b.py Widget --insert-after existing_fn

Moved blocks are spliced immediately after existing_fn in the target. Without --insert-after they are appended at the end; naming an absent symbol appends at the end and records a warning.

Move without copying local helpers

Bash
axm-anvil move src/mylib/a.py src/mylib/b.py Widget --no-include-helpers

Transitively-referenced local helpers and constants are left behind (imports the moved code needs are still copied). A include_helpers=False: not copied into target: <names> warning lists what was skipped.

Migrate gradually with a re-export shim

Bash
axm-anvil move src/mylib/a.py src/mylib/b.py Widget --reexport

Callers are left untouched; a from b import Widget # re-export for backwards compat line is injected into the source to support explicit imports from the old module. Review literal exports and import-time behavior separately; this does not prove full backwards compatibility.

Catch import cycles before writing

Bash
axm-anvil move src/mylib/a.py src/mylib/b.py Widget --check

Simulates the move (including caller rewrites) and fails with ImportCycleError if it would introduce a new import cycle. Pre-existing cycles are ignored.