Command-line tool (uf)¶
uf is the command-line tool of Update Factory. It calls the same Management API as the MCP server, has one command for every operation of the server, and is released together with it under the same version number. It is available from version 0.2.0. Use it from a terminal, in scripts and CI/CD pipelines, and with AI agents.
For AI agents, we recommend uf
uf is the tool Kynetics recommends for operating Update Factory with AI agents, and it suits several tenants in particular:
- Every call names its environment and tenant (
--envand--tenant) and nothing is remembered between calls. One agent can work on many tenants and cannot slip onto the wrong one by accident. The MCP server serves one fixed environment and tenant per process: several tenants mean several server entries. - Every call prints on stderr the environment, tenant, API URL and API client it used, so you and the agent can see where a change went.
- The API client secret stays in the credentials file: the agent never has to type or see it, and you add a tenant with
uf auth addin your own terminal. - An agent skill ships with the tool and teaches the agent all of this: see Let an AI agent use uf.
The MCP server remains a good choice when your client gives the agent no shell.
Before you start¶
You need four things from Kynetics:
- An API client for your tenant (a name and a secret). To request one, open a ticket; see Bearer Token (OAuth 2 client credentials).
- The index URL of the private package index, ending in
/simple/(written<INDEX_URL>below). - A read-only index user and its password.
- The version to install,
0.2.0or later (written<VERSION>below). Use the same version as the MCP server if you use both: they are released together.
You also need uv, which installs the tool and downloads it from the index.
Install¶
Give uv the credentials of the private index first: it is step 1 of the MCP server page, and it is done once for both tools. Then install the tool:
uv tool install --index <INDEX_URL> updatefactory-cli==<VERSION>
uf --version
uv tool install puts uf in an environment of its own and links the command in a folder of executables (uv tool dir --bin prints it). If uv warns that this folder is not in your PATH, run uv tool update-shell and open a new terminal. uf --version must print uf <VERSION>.
To update, run the same command with the new version: uv replaces the installed one. The index and the netrc file are needed only to install or update: uf itself talks only to the Update Factory API.
To run uf once without installing it:
uvx --index <INDEX_URL> --from updatefactory-cli==<VERSION> uf --version
uvx contacts the index at every start (see Pin and update): for daily use, and for an agent, install the tool.
List the available versions¶
The private index is a standard Python simple index: the page of a package lists every file it holds, and so every version you can install. With the netrc file you created for uv (see step 1 of the MCP server page), curl authenticates by itself:
curl -s --netrc <INDEX_URL>updatefactory-cli/ | grep -oE '>updatefactory_cli-[^<]+<'
<INDEX_URL> ends in /simple/, so the package name follows it directly and the URL ends with a /. Each line is a file name that contains a version, for example updatefactory_cli-<VERSION>.tar.gz. On Windows curl reads %USERPROFILE%\_netrc; for a file kept elsewhere use --netrc-file <PATH>. The MCP server is listed the same way, with the package name updatefactory-mcp-server.
Save the API client credentials¶
uf reads the same credentials file as the MCP server, at the same path on each system and with the same layout: see step 3. If your API client is already there, check that uf finds it:
uf --env <ENV> --tenant <TENANT> auth status
<ENV> is the tier of your tenant, business or personal: the value you give to UF_ENV for the MCP server. The answer must show "credential_source": "file".
Otherwise add the API client. uf asks for the secret at a hidden prompt: there is no option to put it on the command line, where other users of the machine could see it.
uf --env <ENV> --tenant <TENANT> auth add --client-id <API_CLIENT_NAME>
uf auth add creates the folder with mode 700 and the file with mode 600, and keeps the other entries of the file.
The file is %APPDATA%\updatefactory\credentials.json, inside your user profile. Windows has no chmod: access follows the permissions of the profile folder, so do not move the file out of it and do not share it.
- For a script,
--client-secret-file <PATH>reads the secret from a file only you can read, and--client-secret-file -from standard input, for example from the command of your secret manager. - A pair that is already in the file is refused unless you add
--force. uf auth addchecks nothing against the server: a wrong secret shows up as exit code 3 at the first call.uf auth listprints the environment and tenant pairs that have credentials. It never prints a secret.
First call¶
uf --env <ENV> --tenant <TENANT> targets list --limit 5
The answer is one JSON document on stdout. Before it, uf prints on stderr one line that names the context it used:
uf: env=<ENV> tenant=<TENANT> base_url=https://mgmt.<ENV>.updatefactory.io client_id=<API_CLIENT_NAME> source=file
A list of targets, even an empty one, means that the credentials work. --format table prints a table on stderr instead of the JSON, and --quiet turns the context line off. uf --help lists the command groups (targets, distribution-sets, software-modules, rollouts, actions, the types, tags and filters, system-config, limits) and --help after any command describes it, with a runnable example when it takes a body.
Work on several tenants¶
A uf call serves one environment and tenant pair and keeps nothing for the next one, so with several tenants:
- Run
uf auth listto see which pairs have credentials. It works offline. - Pass
--envand--tenanton every call. Do not rely onUF_ENVandUF_TENANT: a forgotten variable would silently point the call at another tenant. - Do not set
UF_CLIENT_IDandUF_CLIENT_SECRET: they are one credential that wins over the file for every tenant.uf auth listshows"env_override": truewhen they are set. - Read the context line on stderr: it names the pair the call acted on.
uf --env <ENV> --tenant <TENANT_A> targets list
uf --env <ENV> --tenant <TENANT_B> targets list
Let an AI agent use uf¶
uf skill install gives your agent the uf-cli skill: the rules above, in the format that Claude Code, opencode and Codex load when the agent needs to run uf. The skill ships with the tool and carries its version.
uf skill install # every agent found in your home folder
uf skill install --agent claude --scope project # .claude/skills of the current folder
uf skill install --dry-run # only report what would be written
--agent |
--scope user (default) |
--scope project |
Read by |
|---|---|---|---|
claude |
~/.claude/skills/uf-cli/ |
.claude/skills/uf-cli/ |
Claude Code, opencode |
agents |
~/.agents/skills/uf-cli/ |
.agents/skills/uf-cli/ |
Codex, opencode |
On Windows, ~ is your user profile folder (%USERPROFILE%), and the project folder is the one you run the command in.
- Without
--agent,ufinstalls for each agent whose folder exists in your home:~/.claudeforclaude;~/.codex,~/.agentsor~/.config/opencodeforagents. If it finds none, it exits with code 2: name the agent with--agent. - The result lists each folder as
created,updated,unchangedorreplaced. Run the command again after you updateuf, so that the skill matches the version. ufoverwrites only a skill it installed itself, refuses anotheruf-cliskill unless you add--force, never follows or replaces a symbolic link and deletes nothing.- To remove the skill, delete its folder (for example
rm -r ~/.claude/skills/uf-cli, orRemove-Item -Recurse $env:USERPROFILE\.claude\skills\uf-clion Windows), then restart the agent. There is nouf skill uninstall. - For any other agent,
uf skill showprints the skill as Markdown: copy it to where your agent reads skills, or into its instruction file (AGENTS.md,CLAUDE.md).
Restart the agent, then ask it:
Which Update Factory tenants do I have credentials for? Then list 5 targets of the
<TENANT>tenant.
The agent runs uf auth list, then uf --env <ENV> --tenant <TENANT> targets list --limit 5.
What the skill tells the agent to do:
- Pass
--envand--tenanton every call, and check the context line. - When a pair has no credentials, ask you to run
uf auth addin your terminal. It never types a secret, puts one on a command line or reads the credentials file. - Ask for your approval before a destructive command, naming the tenant and what will be deleted (see below).
- Not paste the secrets that some answers contain into a chat or a log (see below).
The skill pre-approves no command, and your agent still asks before it runs a shell command, unless you allow it. To let Claude Code run uf auth list without asking, add Bash(uf auth list*) to your permission settings.
Warning
An agent that can run shell commands as you can read every file you can, including credentials.json. The skill tells it not to, but a rule in a skill is not a barrier: use the permission settings of your agent to deny it access to that file.
Bodies, answers and exit codes¶
Commands that create or change something take a --body in JSON, in the camelCase of the REST API: inline, from a file with @file.json, or from standard input with -. A body inline needs quoting that depends on your shell, so on Windows keep the body in a file (UTF-8):
uf --env <ENV> --tenant <TENANT> targets create --body '{"controllerId": "dev1", "name": "Device 1"}'
Windows PowerShell and PowerShell 7 do not pass double quotes to programs in the same way, and PowerShell reads a leading @ as special syntax: quote the file name.
uf --env <ENV> --tenant <TENANT> targets create --body '@dev1.json'
uf --env <ENV> --tenant <TENANT> targets create --body @dev1.json
When a call fails, uf writes one JSON object on the last line of stderr ({"status": "error", "kind": "...", "message": "..."}) and exits with a code that names the class of the failure:
| Code | Meaning |
|---|---|
| 0 | Success. |
| 1 | Unexpected error. |
| 2 | Invalid input: a wrong option or argument, an invalid body. |
| 3 | Authentication: no credentials, a refused login, HTTP 401 or 403. |
| 4 | The server failed (5xx or another error status), or an artifact --url cannot be downloaded. |
| 5 | Not found. |
| 6 | A destructive command was refused because it was not confirmed. |
| 7 | No answer from the network: DNS, refused connection, timeout. |
| 8 | The state of the resource refuses the request (HTTP 405, 409, 412 or 423). |
Every delete, targets batch-delete, distribution-sets invalidate and system-config reset is refused until it is confirmed: in a terminal, uf asks you; in a script or for an agent, it exits with code 6 and sends no request, and the message gives the command to run again with --yes. The agent shows you the tenant and what will be deleted, and runs it only after you approve. Commands that change devices or the tenant without deleting, such as targets assign-ds, the rollouts lifecycle commands and system-config set, are not gated: the skill has the agent run them only when you asked, and name the tenant first.
Some answers contain secrets
uf prints the answers of the API as they are. targets get and targets list include the securityToken of each target, and system-config get and system-config list include the gateway token (authentication.gatewaytoken.key). When token authentication is enabled for your tenant, the security token lets whoever holds it act as that device towards the device API, and the gateway token as any device of the tenant.
Do not paste these answers into chats, tickets or logs. What an AI agent reads is usually sent to its model provider and kept in the history of its session: ask the agent to run these four commands only when you need them.
Troubleshooting¶
uf: command not found ('uf' is not recognized on Windows)
: The folder that uv tool dir --bin prints is not in your PATH. Run uv tool update-shell and open a new terminal.
Exit code 3 with credentials_missing
: No credentials for that environment and tenant. Run uf auth list to see which pairs exist, and uf auth add for the missing one. The environment and tenant in the context line must be the ones you meant.
Exit code 3 with token_request, or api_auth (HTTP 401 or 403)
: token_request: the login was refused, so the API client name or secret is wrong. api_auth: the credentials are accepted but the API client has no permission for this operation; see the 403 entry of the troubleshooting of the MCP server page.
Exit code 6
: The command deletes or invalidates something and was not confirmed. This is expected: read the tenant and the subject in the message, and run the command given in rerun only if they are right.
Exit code 7
: uf got no answer from the API or from the token endpoint. Check the network and the proxy settings of the terminal, and try again: the credentials were not judged.
401 Unauthorized while installing or updating uf
: The index credentials: see the first entry of the troubleshooting of the MCP server page.