> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentx.wft/llms.txt
> Use this file to discover all available pages before exploring further.

# agentx config

> List, get and set the settings of one machine.

Machine settings live in `settings.json` in agentx home. They never leave the machine.

## List every setting

```sh theme={null}
agentx config list
```

```text theme={null}
schema_version           1
label                    my-laptop
auto_push                false
accept_operations        false
ignore_system_files      true
disabled_configurations  (none)
sources                  []
copy_mode                {}
```

An empty setting shows as `(none)`. In a terminal the keys are cyan and `true` is green.

| Key | Meaning |
| - | - |
| `schema_version` | The settings file format version. |
| `label` | The machine label. Until you set it, it is the hostname. |
| `auto_push` | Whether published forks are pushed automatically. |
| `accept_operations` | Whether the machine executes operations queued for it. |
| `ignore_system_files` | Whether the files your operating system or editor leaves in a skill, such as `.DS_Store`, `Thumbs.db`, `*.swp` and `*~` backups, are ignored when agentx compares, diffs and reverts it. On by default. See [Files that do not count](/cli/skill#files-that-do-not-count). |
| `disabled_configurations` | The agent configurations left out of placements by default. Every other detected configuration is enabled. |
| `sources` | The sources skills are installed from, managed with [`agentx source`](/cli/source). |
| `copy_mode` | The skills placed as a copy instead of a symlink, per configuration. Written by `agentx skill add --copy` and `agentx skill place --copy`, and cleared by `agentx skill remove`. |

## Get one setting

```sh theme={null}
agentx config get label
```

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

## Set a setting

```sh theme={null}
agentx config set label "work laptop"
agentx config set auto_push true
```

```text theme={null}
✓ label is now work laptop
```

Set `label`, `auto_push`, `accept_operations` or `ignore_system_files`. The booleans take `true` or `false`. A label is one non-empty line of at most 256 bytes with no control character in it. Any other value, an unknown key, or a key this command cannot change exits with code 1.

The write is atomic: the file is replaced whole, or not at all. If another agentx command is running, the command exits with code 7 at once; retry when it finishes.

## Enable or disable a configuration

```sh theme={null}
agentx config disable windsurf
agentx config enable windsurf
```

```text theme={null}
✓ windsurf is now disabled
✓ windsurf is now enabled
```

Every agent configuration `agentx scan` detects is enabled from the start. Disable one to leave it out of placements by default; enable it to put it back. Use the id shown in parentheses by `agentx scan`. An id that is not detected exits with code 5 and lists the detected ids. Disabling a configuration does not stop its client from reading the library.

Enabling only decides where later installs go. To fill a newly enabled client with what you already have, add `--place-all`:

```sh theme={null}
agentx config enable cursor --place-all
```

```text theme={null}
✓ cursor is now enabled
✓ placed 2 skills in cursor
  pdf   symlink  ~/.cursor/skills/pdf -> ~/.agents/skills/pdf
  xlsx  symlink  ~/.cursor/skills/xlsx -> ~/.agents/skills/xlsx
```

Each skill placed gets one row: its placement in Cursor's own skills directory. A skill Claude Code also holds is one row too, although Cursor reads Claude Code's skills directory as well; `--json` lists both paths.

Each skill is placed as a symlink, except in a configuration where agentx already keeps a copy of it: that one gets a copy again, as with [`agentx skill place`](/cli/skill).

The setting and every placement it implies are one change, written down before anything on disk moves. A run interrupted part way is finished by the next agentx command rather than undone.

A placement agentx cannot make does not fail the run. If something you put there yourself is already at one of the paths, or agentx cannot write the client's skills directory, it leaves that path alone and names it, places the rest, and still succeeds, so the client can end up enabled with part of the library in it:

```text theme={null}
warning: ~/.cursor/skills/pdf is not this skill and was left as it is; no placement was made for cursor
✓ cursor is now enabled
✓ placed 1 skill in cursor, 1 placement skipped
  xlsx  symlink  ~/.cursor/skills/xlsx -> ~/.agents/skills/xlsx
```

Here Cursor does not see pdf at all, so pdf has no row. If agentx left Cursor's path alone and Cursor still sees the skill through another client's skills directory, as it sees a skill Claude Code holds, the skill's row shows that path instead, so the output still tells you Cursor has the skill.

A copy agentx keeps for the client is skipped the same way when it is different from the library, for instance because you edited it. It stays exactly as it is, and the line under the warning names the commands that replace it with the library version:

```text theme={null}
warning: cursor's copy of pdf is different from the library, so it was left unchanged (~/.cursor/skills/pdf)
  to replace it with the library version: agentx skill remove pdf --from cursor && agentx skill place pdf --to cursor --copy
✓ cursor is now enabled
✓ placed 1 skill in cursor, 1 placement skipped
  xlsx  symlink  ~/.cursor/skills/xlsx -> ~/.agents/skills/xlsx
```

The kept copy is not the library's pdf, so pdf has no row here either. If Cursor also sees pdf through another client's skills directory, pdf's row shows that path, as above.

See [A copy that differs from the library](/cli/skill#a-copy-that-differs-from-the-library).

`--place-all` belongs to `enable`; `agentx config disable --place-all` exits with code 1. Place skills one at a time with [`agentx skill place`](/cli/skill).

A client that reads the library directly, such as Codex, already sees every library skill, so `--place-all` makes no entry of its own for it and says so:

```text theme={null}
✓ codex is now enabled
✓ codex reads the library and already sees 2 skills; nothing was placed
  pdf   library  ~/.agents/skills/pdf
  xlsx  library  ~/.agents/skills/xlsx
```

## Script it

Add `--json` to any `config` command to get a `settings` event with every setting as an object:

```sh theme={null}
agentx --json config set auto_push true
```

```json theme={null}
{"type":"settings","schema_version":1,"settings":{"schema_version":1,"label":"work laptop","auto_push":true,"accept_operations":false,"ignore_system_files":true,"disabled_configurations":[],"sources":[],"copy_mode":{}}}
{"type":"result","schema_version":1,"ok":true}
```

## Fix a broken file

If `settings.json` cannot be parsed, every `config` command exits with code 10 and names the file. Fix the JSON, or delete the file to start again from defaults.


## Related topics

- [agentx machine](/cli/machine.md)
- [agentx skill](/cli/skill.md)
- [agentx](/index.md)
- [agentx scan](/cli/scan.md)
- [Output and exit codes](/cli/output.md)