CLI
Anchorpoint has a command line interface that can be used to control file locks, trigger Git commands or create custom scripts for pipeline development. The CLI can be run from the terminal or any other external application.
Examples using the CLI
Cinema 4D asset publisher
This light plugin creates a context menu entry in Cinema 4D and triggers a publishing process that creates a master file and sets metadata in Anchorpoint. View the source on GitHub.
Unreal Engine plugin
This plugin allows to use the revision control provider in Unreal Engine. Users can submit files from the Unreal Editor and view the status of the assets in the content drawer. View the documentation and the source on GitHub.
Unity plugin
The Unity plugin allows to commit files directly from the Unity Editor, and use file locking on any Unity asset. View the documentation and the source on GitHub.
Path to executable
Windows: C:\Users[USERNAME]\AppData\Local\Anchorpoint\app-[LATESTVERSION]\ap.exe
macOS: /Applications/Anchorpoint.app/Contents/Frameworks/ap
Note: You can also add the cli to your PATH if you want to access it more easily.
Note on Anchorpoint updates
After each Anchorpoint update, the version number contained in the name of the Anchorpoint installation directory changes. If you are building a plugin that uses the CLI, make sure you add the appropriate logic to navigate to the latest version of Anchorpoint and select the CLI executable from there.
def get_executable_path()
base_path = os.path.join(os.getenv('LOCALAPPDATA'), "Anchorpoint")
pattern = r"app-(\d+\.\d+\.\d+)"
cli_executable_name = "ap.exe"
# Get directories matching the pattern
versioned_directories = [
d for d in os.listdir(base_path)
if re.match(pattern, d)
]
# Sort directories by version
versioned_directories.sort(key=lambda d: tuple(map(int, re.match(pattern, d).group(1).split('.'))), reverse=True)
if versioned_directories:
latest_version_path = os.path.join(base_path, versioned_directories[0])
cli_path = os.path.join(latest_version_path, cli_executable_name)
return cli_path
An example written in Python how to get the proper CLI path
CLI commands
In each call, you have to provide the current project directory of you Anchorpoint project, and then the commands. The basic structure is
ap [OPTIONS] [SUBCOMMAND]
The following command is similar to a git status on your project, but it includes information about outdated and locked files:
ap status
By default, the CLI will look for the project in the current working directory. You can always overwrite your current working directory using the --cwd option, e.g.:
ap --cwd "C:\Repositories\myGameProject" status
Options
| -h,--help | Print this help message and exit |
| --config | Read an ini file. |
| --print-config | prints the command configuration that can be used with the --config parameter. Does not execute the command |
| --cwd TEXT | Set the current project directory |
| --json | print output as json to stderr |
| --apiVersion | the version of the json output (and input). Set it to 1 to ensure consistency |
Subcommands
| sync | Syncs the current state of the project with the server |
| commit | Commits the current state of the project |
| status | Shows file status including locks and outdated files |
| pull | Pulls the latest changes from the server |
| push | Pushes the latest changes to the server |
| revert | Reverts changed files |
| user | User operations, most importantly user list |
| lock | Lock operations, e.g create, list, remove |
| thumbnail | Thumbnail operations, e.g. set, get |
| config | Update configuration values using set, get, and unset |
| python | Runs a python script with Anchorpoint context |
| git | Run any Git operation |
| connect | Starts ap CLI as a daemon that connects to running instance of Anchorpoint |
A script would always pass --json to make parsing simpler. When JSON is enabled, it will output the JSON to stderr to separate the output from non json.
You can pass —-cwd to set the current project directory. That should usually be the project path where Anchorpoint also stores the .approj file. Note that an Anchorpoint project is required for most commands.
If you terminate ap.exe, the operation is cancelled gracefully. Some commands will output progress, see sync example.
Please make sure to always call the ap.exe with —-apiVersion 1 so that the output protocol is guaranteed.
If an error occurs with —-json flag being set, the error is in JSON format as well.
Output
{"error": "whatever"}
Commands
Sync files
sync
Syncs files to the server (this internally invokes Git commit, pull, and push including Anchorpoint's optimizations). It also releases locks.
Example - sync all files
ap —-json sync —-message “Some commit message”
Example - sync a single file
ap —-json sync —-files “relative_path_to_file_A.png” “another_file.txt” —-message “Some commit message”
It will output progress, again here with —-json flag. It has an optional progress-value from 0 to 100. The upload progress is currently only text based. The progress value for upload is number of file based. So uploading 4 files will jump from 0% to 25% if file 1 is uploaded - even if the other files are bigger or smaller.
Output
{"progress-text": "Finding binary files"}
{"progress-text": "Staging files"}
{"progress-text": "Pushing Changes"}
{"progress-text": "Pushing Git Changes"}
{"progress-text": "Uploading Files: 0% (0/2), 0 B | 0 B/s"}
{"progress-text": "Uploading Files: 0% (0/2), 1.3 MB | 0 B/s", "progress-value": 0}
{"progress-text": "Uploading Files: 5% (0/2), 2.1 MB | 956 KB/s", "progress-value": 0}
There are equivalent commands if you only want to commit, push, or pull files. Just invoke ap commit —-help, for example
Caution: The command line on Windows and Mac only allow a certain amount of characters to be passed. So if the user wants to sync e.g. 1000 files, this most likely won't work. We recommend to use the print-config command and replicate that format and read it with --config so that the sync command reads the files from the config and not through the terminal
Commit Files
commit
The commit command commits the current state of the project. It stages changes, adds binary file types as LFS automatically and creates a commit in the repository.
Example
ap commit —-files “relative_path_to_file_A.png” “another_file.txt” —-message “Some commit message”
Pull Files
pull
The pull command fetches and integrates changes from the server into the local project. It also works when changed files are not committed yes as long as there are no conflicts.
Example
ap pull
Push Files
push
The push command uploads local changes to the server, updating the remote repository. Anchorpoint performs first a Git LFS push and then the Git push.
Example
ap push
Status
status
Get status of files, locks, and outdated files (files that are newer on the server).
Example
ap —-json status
Output
{
"current_branch": "main",
"staged": {},
"not_staged": {
"deleted_file.txt": "D",
"modified_file.bin": "M",
"conflicting_file.bin": "C",
"added_file.dat": "A"
},
"locked_files": {
"Assets/Blender/some.blend": "devs@anchorpoint.app",
"image.png": "devs@anchorpoint.app"
},
"outdated_files": ["Assets/Blender/house.blend", "Assets/Blender/car.blend"]
}
You can optionally provide a list of paths to filter the status
ap —-json status --paths "some fine file.blend" "assetFolder"
You can also only show outdated files
ap —-json status --outdated
Output
{
"current_branch": "main",
"outdated_files": ["Assets/Blender/house.blend", "Assets/Blender/car.blend"]
}
Revert files
revert
Reverts and unlocks provided files. If no files are provided it will revert ALL files.
Example
ap revert --files "some_file.blend" "another.uasset"
List all users
user list
Lists all users of a given project with detailed information. The "current" user is the logged in user.
Example
ap --json user list
Output
[
{
"id": "some id",
"email": "peter@anchorpoint.app",
"name": "Peter",
"picture": "",
"level": "admin",
"pending": "0",
"current": "1",
},
{
"id": "another id",
"email": "devs@anchorpoint.app",
"name": "John",
"picture": "",
"level": "owner",
"pending": "0",
"current": "0",
}
]
File locking
lock create lock remove lock list
Locks in Anchorpoint are usually handled automatically if the project is open in Anchorpoint and files are changed. That said you can lock and unlock files manually using the CLI.
You can also disable automatic locking for a file using the config command, see below.
Example
ap lock create --git —-files “a_file.bin” “another.txt”
The --git flag is important, so that Anchorpoint knows to unlock the file automatically on push or revert
If you lock a file that is not yet changed, use —-keep to tell Anchorpoint to not automatically unlock the file as it's unchanged.
To remove locks, call
ap lock remove —-files “a_file.bin” “another.txt”
If you want to see all locks, either call ap status or ap lock list
Get and set thumbnails
thumbnail set thumbnail get
To update a thumbnail for a single file (--file) you can pass a detail and preview file.
Example - set a thumbnail
ap thumbnail set --file "some.uasset" —-detail “path to png” —-preview “path to other png”
Example - get a thumbnail
If you ever need to, you can also get the thumbnails for files.
ap —-json thumbnail get --files "some.uasset" "another.unity"
Output
{
"thumbnails": [
{
"filename": "some.blend",
"thumbnails": [
{
"type": "preview",
"path": "path to thumbnail png"
},
{
"type": "detail",
"url": "path to thumbnail png"
}
]
},
{
"filename": "another.unity",
"thumbnails": []
}
]
}
Get project or file history
log
You could do this using git, but the ap cli offers a simpler shortcut.
Example
ap --json log --file "some.uasset" -n 10
This will print the last 10 commits of a a file. The --file can be omitted to get the history of the project instead. If -n is omitted, it will print all commits (caution, can be a lot!). It's highly discouraged.
Output
[
{
"commit": "8b614a5eb32aabca31345e094bfed4ea8ef4e415",
"author": "devs@anchorpoint.app",
"date": 1723551004,
"message": "A commit message"
},
{
"commit": "8d56be3aa601de72c1727314ea29bd4f9d2661f1",
"author": "devs@anchorpoint.app",
"date": 1723543736,
"message": "A commit message"
},
{
"commit": "97939fabdfb5215f6203cc8dc66c6d3529c396c7",
"author": "devs@anchorpoint.app",
"date": 1723282062,
"message": "A commit message"
}
]
Configuration
config get config set config unset
You can get and set config values using to e.g. modify Anchorpoint's project settings.
Example
ap config set git-auto-lock false
ap config get git-auto-lock
Setting git-auto-lock will toggle the Automatically lock Changed Files in the project settings.
Custom Configurations
You can also prefix keys to add them to your own settings instance.
ap config set unreal/my_setting true
You can access this config setting in python like so.
settings = apsync.Settings("unreal")
my_setting = settings.get("my_setting", False) # key, default
Disable automatic locking for paths
You can also disable automatic locking just for a specific path in your project. The Unreal Engine plugin disables automatic locking for it's project directory, for example
ap config set unreal/git-auto-lock-path false
Run python script
python
You can use the built-in Anchorpoint Python interpreter to run arbitrary scripts. Our interpreter comes with built-in Anchorpoint context and anchorpoint and apsync Python modules.
Note that some variables of the anchorpoint module, that are passing over UI values, are not available. For example you cannot get the selected files, which are normally provided by the anchorpoint.get_context() function.
ap python --script “absolute or relative path to script” --args "test"
Relative paths are scripts within your project. So if you call
ap --cwd "C:\Repositories\MyGame" python --script “scripts\publish.py”
The script C:\Repositories\MyGame\scripts\publish.py is called.
Here is an example script, it can be called like this ap python --script example.py --args "test"
import sys
import anchorpoint
import apsync
def main():
sys.__stdout__.write("sys.argv: " + sys.argv)
ctx = anchorpoint.get_context()
sys.__stdout__.write("anchorpoint context: " + ctx)
project = apsync.get_project(ctx.path)
if project:
sys.__stdout__.write("anchorpoint project: " + project.name)
else:
sys.__stdout__.write("no anchorpoint project found ")
if __name__ == "__main__":
main()
Run any Git command
git
It might be necessary to invoke git commands directly. You cannot rely on installed git versions, as some users only have Anchorpoint. Using our provided git version ensures a correct git LFS setup and injects git credentials automatically.
Example
If you need to pass quoted paths, use outer double and inner single quotes.
ap git -c "checkout -- 'Content/Characters/Character Main.uasset'"
Connect with IPC
connect
Using this command will connect your plugin to Anchorpoint using a constant connection. It will create a subprocess that is running constantly as a daemon, attached to your main application.
Example
ap connect —-name “blender”
The connect command will print information or commands to stdin (note: not stderr) as JSON.
The command is printing information about locked and outdated files as well as if the project is currently selected in Anchorpoint and if it's dirty (files have changed) (example using —-pretty flag):
{
"files": [
"car.mtl"
],
"id": "496c13f5-450c-4a83-8d63-84e49bc02c77",
"type": "files locked"
}
{
"files": [
"car.mtl"
],
"id": "2c24b517-9c5b-48c4-98a7-c5b8e4ed5d4f",
"type": "files unlocked"
}
{
"files": [
"car.mtl"
],
"id": "924f6de7-b753-4573-8c21-d429e4f990d2",
"type": "files outdated"
}
{
"files": [
"car.mtl"
],
"id": "c6b3d024-dd80-495d-b16f-987bc482247e",
"type": "files updated"
}
{
"id":"b0aebab6-985c-4deb-b23a-a01c773fb923",
"type":"project opened"
}
{
"id":"3caf8a74-67e4-4d14-8116-cd9651144488",
"type":"project closed"
}
{
"id":"7e07886a-3cc8-4a3b-ad03-407b25644fb1",
"type":"project dirty"
}
This is only for your information and motivates you to call ap status for example to update the plugin UI.
A brief description of each info type:
| files locked | Files have been locked |
| files unlocked | Files have been unlocked |
| project opened | The current project is currently opened in Anchorpoint. This enables files outdated, updated, and dirty |
| project closed | The project is not selected in Anchorpoint. files outdated, updated, and dirty are disabled |
| files outdated | Files are outdated, aka they are not in sync with the state on the server |
| files updated | The files are in sync with the server again |
| project dirty | Some files in the project have changed. Good idea to call ap status command again |
A note about caching: When “project opened” is emitted it is save to cache state in the integration plugin. You can cache all locked and outdated files as well as git modification state. It can be as simple as caching the result of ap status and re-populate the cache with ap status when an update info (locked, unlocked, outdated, updated, dirty) is emitted. When “project closed” is emitted, you can only cache locks, they are emitted independent of a project.
Command actions
When running connect command, there are a few optional parameters that will tell Anchorpoint that the plugin can perform certain actions. All actions assume a JSON response from the plugin. If the response is not received within 5s, the commands ignores the plugin response.
To respond to a command provide this to stdin, this will tell Anchorpoint that you did perform the requested action.
Positive Response
{"id":"924f6de7-b753-4573-8c21-d429e4f990d2"}
If you cannot perform the action (e.g. your game engine is in an invalid state), provide an error
Error Response
{"id":"924f6de7-b753-4573-8c21-d429e4f990d2", "error":"Engine is in play mode"}
The actions are the following:
ap connect -n “engine” —-projectSaved
Anchorpoint will ping the plugin to verify that files are saved (or all files if files argument is missing).
{
"files": [
"car.mtl"
],
"id": "924f6de7-b753-4573-8c21-d429e4f990d2",
"type": "project saved"
}
If the project is saved, response positive, if not respond with an error. Ideally, make sure that the error message follows this pattern: "foo.uasset is unsaved\nfolder/bar.uasset is unsaved" This will allow Anchorpoint to present a custom dialog to the user instead of just an error toast.
ap connect -n “engine” —-changedFiles
Anchorpoint will ping the plugin with “files about to change” and “files changed”. Use this to e.g. unlink files in your application so that they can be overwritten and reloaded accordingly
{
"files": [
"car.mtl"
],
"id": "924f6de7-b753-4573-8c21-d429e4f990d2",
"type": "files about to change"
}
ap connect -n "unity" —-thumbnails "unity" "whatever"
Anchorpoint will ping the plugin to provide thumbnails for files that match the specified extensions
{
"files": [
"car.unity"
],
"id": "924f6de7-b753-4573-8c21-d429e4f990d2",
"type": "request thumbnails"
}
The plugin should set the thumbnails using the ap thumbnail set command and then respond positively.