Skip to main content
Machine settings live in settings.json in agentx home, ~/.agentx by default. agentx does not sync them. To copy them to another machine, use agentx export. This page uses the terms configuration, library and placement. See the glossary.

List every setting

An empty disabled_configurations shows as (none). sources and copy_mode print as one line of JSON.

Get one setting

The command prints the bare value, so a script can use it directly. For an unknown key, agentx exits with code 1 and lists the keys.

Set a setting

You can set label, accept_operations and ignore_system_files:
  • accept_operations and ignore_system_files take true or false.
  • A label is one non-empty line of at most 256 bytes with no control character in it.
agentx exits with code 1 for an invalid value, an unknown key, or a key you cannot set. For a key, the error lists the keys you can set. If another agentx command is running, the command stops with exit code 7. Run it again when the other command finishes.

Enable or disable a configuration

Every configuration agentx scan detects starts enabled. When you install or place a skill without --to, agentx places it only in enabled configurations. Disable a configuration to skip it. Enable it to include it again. Use the id that agentx scan shows in parentheses. For an id that scan does not detect, agentx exits with code 5 and lists the detected ids. A client that reads the library directly, such as Codex, still sees every skill when you disable it. See Clients that see every skill.

Place the skills you already have

Enabling a client changes only where later installs go. To also place every skill in your library in that client, add --place-all:
The output has one row for each skill, with its path in Cursor’s skills directory. agentx places each skill as a symlink. If agentx already keeps a copy of a skill for this client, it places a copy. See Copy instead of link. If the run stops part way, the next agentx command finishes it. A client that reads the library directly, such as Codex, already sees every skill. See Clients that see every skill. For such a client, --place-all places nothing and lists what the client sees:
To place one skill at a time, use agentx skill place.

When a placement is skipped

agentx skips a placement when something of yours is already at the path, or when it cannot write to the client’s skills directory. It prints a warning for each skipped path, places the other skills, and exits with code 0. The client is then enabled with only some of your skills:
Cursor does not see pdf, so pdf has no row. If Cursor sees pdf through another client’s directory, such as Claude Code’s, the row shows that path. agentx also skips a copy it keeps for the client when the copy differs from the library, for example because you edited it. The copy stays as it is. The warning names the commands that replace it:
See A copy that differs from the library.

Remove a configuration

To delete the configuration directory of a client, name the client:
agentx deletes each directory with everything in it: skills, MCP server declarations, plugins, settings and history. It also takes the client out of disabled_configurations and copy_mode. agentx scan no longer detects the client. Your library stays as it is, and so does a skills directory outside the configuration directory, such as the one Amp reads in ~/.config/agents/skills. Some clients share a directory. Zencoder and Zenflow keep one configuration directory, and Antigravity’s directory is inside Gemini CLI’s. When you remove a directory, agentx removes every client in it and lists each one. agentx refuses to delete a directory that is, or holds, your library, agentx home or your home directory, and exits with code 6. If the run stops part way, the next agentx command finishes it.

Confirm without a terminal

The command asks once before it deletes anything. Pass --yes to answer in advance:
Use --yes in scripts, with --json, and wherever there is no terminal. Without --yes, the command exits with code 6 and changes nothing in these cases. It does the same when you answer anything other than y or yes.

Fix a broken file

If agentx cannot parse settings.json, every command that reads it exits with code 10 and names the file. Fix the JSON, or delete the file to start again from defaults. If a later version of agentx wrote settings.json, every command that reads it exits with code 10 and says which schema version the file has. Upgrade agentx to that version. Keep the file: it holds sources and settings the later version needs. agentx doctor shows the same error in its settings row.

Exit codes

For what each code means, see Exit codes. These causes are special to agentx config:
  • 1: an invalid value, an unknown key, or a key you cannot set.
  • 5: config enable, config disable or config remove names a configuration agentx scan does not detect.
  • 6: config remove was not confirmed, or the directory holds your library, agentx home or your home directory. See Remove a configuration.
  • 7: another agentx command is running. set, enable, disable and remove stop at once.
  • 10: agentx cannot parse settings.json, or a later version of agentx wrote it. See Fix a broken file.