Tank command within centralised config (ADN article)

Pipeline Integrations
, ,
1

FPTR Tank Command

Written by @Felix.Onsare and @sergio.leon.

Flow Production Tracking’s Pipeline Toolkit comes with a command‑line interface called tank, which provides direct project control and is key to handle many Studio workflows.

Tank Video Overview

We recorded a video with the overview of the tank command. At the moment it can be found in this location:

Tank_command.mp4

Where do we find the tank command?

Every project configuration has its own tank script that you can run from a shell. You will find it on the base root of any project configuration.

image
image940×240 89 KB

Once your project is set up, you can navigate to the project’s configuration folder and execute:

./tank

This uses the dedicated tank command for that project. Artists and TDs can use the tank command to install and update Toolkit apps/engines, launch DCCs with a specific context, create folder structures or perform admin tasks like freezing or sharing the core API.

In most cases, typically you will use the project’s ./tank executable. But there is also a global tank command that can search across projects or execute global commands. This is also sometimes referred as a tank studio command.

The tank command is mentioned many times in the documentation. If we would need to point to the main start reference, that would be:

Authentication

When using tank for the first time, the process will need to authenticate. If it is already cached, and it is not expired, it will use it from there. It supports two authentication methods:

  1. Authenticate with the App Session Launcher using your default web browser

  2. Authenticate with Legacy Flow Production Tracking Login Credentials

Note that toolkit’s session typically lasts for about 24hrs before a user is required to reauthenticate and get a new session token. More on this info here.

Inspect assets

You can search for assets by name. Listing all assets containing a specific text on it, could be done like:

tank Asset pi

or

tank Shot ABC (Show a list of all shots in Shotgun containing the phrase ABC)

Searching for specific commands in a context:

tank (Show what commands are available for the current directory)

tank Shot ABC123 (Show what commands are available for Shot ABC123)

Inspect pipeline configuration

You can list the project configuration. Gives an overview of all the configurations for a project.

tank configurations

To see a breakdown of all the apps and their key configuration settings, you can use:

tank app_info

Checks your environments and settings for consistency. It may take a while to process it. You will find more info in the troubleshooting, validation section.

tank validate

See samples of the output of these commands in the Advanced Toolkit Administration documentation.

Setup new projects

tank setup_project command

There is an advanced studio level hook for controlling the names on new projects created this way. This hook is the Project name hook, and you can read more about it here.

Launching DCCs via Tank

Once apps and engines are installed, tank can launch supported DCCs (Maya, Nuke, Houdini, etc.) under a given Shotgun/FPT context. For example, to open Maya for Shot 1122 in project Bug_Buck_Bunny, you would run:

tank Shot 1122 launch_maya

This tells Toolkit to set its context to the Shot entity with ID 1122 and then start the Maya engine (via the Maya engine’s launch hook). As explained from the Docs, typing ‘tank Shot 1122 launch_maya’ from a console will start Maya in the context of Shot 1122. Other engines have analogous commands (e.g. launch_hiero, launch_nuke, launch_unreal, etc.), corresponding to the launch app hooks in your config. When you launch a DCC through tank, Toolkit will automatically create any missing folders for that context before starting the engine. It will also set up the Flow Production Tracking menu inside the application.

Another sample, to launch the Maya engine for a task with context type Asset, you might run :

tank Asset 'Land with trees’ maya_2026

and Toolkit will open Maya with Asset named ‘Land with trees’ as the current work context, loading the Maya environment’s apps.

Managing Folder Structures

Toolkit’s tank also manages your project’s folder hierarchy on disk based on the configured folder schema. The key commands here are folders and preview_folders. Running the following command,

tank Asset testProp01 folders

creates the full asset folder structure for “testProp01” on disk https://community.shotgridsoftware.com/t/tank-create-folder-command/16942.
You can pass any Entity type (Shot, Asset, Sequence, etc.) and Toolkit will generate all folders defined under that context. If you run

tank folders

with no arguments from the project root, it creates only the top-level folders, it is context-aware. You can also run

tank Asset testProp01 preview_folders

to see what would be created without actually writing files.

Once folders are created, Toolkit registers them in the path cache so that file and path resolution will work. In normal use, folder creation happens automatically when you launch a DCC (as noted above). But if you ever need to manually create or sync folders, use

tank folders [EntityType] [EntityName].

For example:

tank Shot S0100 folders

It will ensure all Shot S0100’s directories (Pipeline Steps, Tasks, publish folders, etc.) exist according to your config.

Updating Toolkit Components

Keeping your Toolkit components up to date is another major role of tank. The updates command walks through your configuration and checks for newer app or engine versions from the Toolkit App Store.
The syntax follow this format:

tank updates [environment_name] [engine_name] [app_name]

with no arguments it will check all environments, engines, and apps, prompting you interactively to apply updates. By specifying an environment, engine, or app, you can narrow the scope of it.

For instance, ‘tank updates Shot’ would check all apps in the “Shot” environment, while ‘tank updates ALL tk-maya tk-multi-loader’ checks the tk-multi-loader app in Maya for all environments. The special keyword ALL can be used to denote every item in a category. Similarly, to update the Toolkit Core API, it is used:

tank core

This checks whether a newer version of the Core is available and offers to upgrade it. Because multiple projects can share a core install, Toolkit asks for confirmation. Administrative tank Commands

Many of these commands are documented in the Advanced Toolkit Administration guide and the command-line help. Together, they allow administrators to script and automate common tasks like cloning configs, freezing updates, or cleaning caches.

Using tank in Distributed Configuration

In a centralized Setup Workflow,

  • you can run ‘tank setup_project to create the config and register it.

  • The configuration folder is placed locally or in a known shared location.

  • All users can point directly to that location.

  • You use tank to maintain the single shared config.

In distributed configurations in FPTr

  • Config is created and uploaded via Flow Production Tracking (Admin UI) — creation may be done with tank, but it does not upload it.

  • the configuration is downloaded and cached locally, instead of living in a shared location.

  • Once on disk, you could find the tank and even run tank commands the same way as with centralized setups, but it is not the recommended approach or intention with distributed configurations. Specially with those commands that changes the configuration. New updates on the remote configuration will create a new cache folder and discard local changes.

Other tank commands

Beyond everyday usage, tank offers a variety of admin commands for configuration management. They are listed when executing ./tank. A few key examples:

  • tank setup_project: Launches the interactive setup wizard to create a new project and configuration (equivalent to the desktop wizard).

  • tank localize / share_core / attach_to_core: Installs the Core API into your current Configuration with attach_to_core. This is typically done when you want to test a Core API upgrade in an isolated way. If you want to safely test an API upgrade, first clone your production configuration, then run the localize command from your clone’s tank command. tank localize embeds a copy of the core in this config, and tank share_core moves it to a common location. More on this here

  • tank push_configuration: Pushes any manual changes (to YAML configs) from a sandbox config back into a production config.

  • tank configurations: Lists all pipeline configurations registered in the ShotGrid project and their locations.

  • tank dump_config: Exports the current configuration to a file or stdout (for review).

  • tank validate: Checks your environments and settings for consistency.

  • tank move_configuration: Moves the config to a new disk location.

  • tank synchronize_folders and tank unregister_folders: These force-sync your local path cache with the database or remove cached folder associations, as described here.

  • tank clear_shotgun_menu_cache: Clears the Toolkit menu cache for this config. This is useful if, for example, new menu actions or changed UI items are not appearing in Flow Production Tracking Desktop or the in-app menus.

  • tank cache_apps / cache_yaml: Manually rebuild the engine/app bundle cache or YAML cache.

Troubleshooting with tank

Debug mode

There are occasions when examining the underlying processes is beneficial, especially when diagnosing unexpected behavior in pipeline operations. By passing the --debug flag to the tank command, verbose output and timing information will be enabled. This provides deeper visibility into internal operations such as context resolution, configuration loading, bundle resolution, and command execution flow, making it easier to understand what the system is doing behind the scenes. This feature can facilitate troubleshooting and provide greater insight into unexpected behavior or issues, particularly when default command output is insufficient for diagnosis.

Additional info about this can be found here.

Validation

Version or dependency conflicts. If engines or apps fail to launch (often with Python or Qt errors), check that you haven’t mixed incompatible versions. For example, running a Maya engine from a config that specifies a different Maya version than installed can cause a crash. Always align your FPTr entities with the actual app installations on disk, and update your pipeline config accordingly. You can use tank app_info to inspect app versions in your env. If the Toolkit core and your environment are misaligned (e.g. you manually changed core versions in config), use tank core to re-sync, or clone your config and test. Also check for long Windows paths or Python 2 vs 3 issues. In short, if you suspect a version conflict, running tank validate can highlight mismatched engine paths or missing dependencies.

Common Issues

In practice, a few recurrent issues with tank arise in real workflows. Here are tips and fixes for the most common ones:

  • Context resolution errors. Errors like TankError: Cannot resolve template data for context usually mean Toolkit couldn’t determine your current FTPr context because the expected folders aren’t registered on disk. This often happens if you try to launch a publish or DCC before creating any folders for that task/asset. The fix is to run the folders command for the missing context. For example, if you see an error about context “Asset door-01” having no folders, run: tank Asset door-01 folders as suggested here. This explicitly creates and registers the folder hierarchy for Asset door-01. In general, launching a DCC via tank (or opening a file via the Workfiles app) will create necessary folders automatically, but if errors occur, running ‘tank [Entity] [Name] folders’ resolves it. Also from the community

  • Path cache mismatches. Toolkit keeps a path cache that maps disk paths to FPTr entitieshttps://developers.shotgridsoftware.com/cbbf99a4/. If you move or rename folders outside Toolkit, your local cache can get out of sync. Symptoms include Toolkit thinking a folder is “not associated with any Flow Production Tracking object.” To fix, use:

    tank unregister_folders [EntityType] [EntityName] 
tank synchronize_folders

    The unregister_folders command removes the cached paths for a given entity, and synchronize_folders then reloads your local cache to match the FilesystemLocation records in the database. reference

  • Storage root misconfiguration. A common setup error is forgetting to define new root paths in Flow Production Tracking’s File Management. For example, if you add a new NFS volume or Linux path to your project’s storage, but do not create a corresponding Local File Storage entry in SG Site Preferences, you may see errors like: “Path /mnt/my_project doesn’t match any defined Local Storage.”. The fix is to go to Site Preferences > File Management in FPTr and add the new root path to the correct Local Storage. More information on this here

  • Stale menu caches. Sometimes after modifying configuration or adding new apps, the Flow Production Tracking (ShotGrid) desktop UI doesn’t immediately show updated menu items. In this case, run:
    tank clear_shotgun_menu_cache
    This clears the local SQLite cache of menu actions for the configuration. The next time you launch Flow Production Tracking Desktop (or the browser UI), it will rebuild the menus from the current config. The internal documentation notes this command specifically for cases where “new or modified Toolkit menu items are not appearing”. Link to github

  • Error module ‘tank’ has no attribute ‘support_url’ when launching Flow Production Tracking Desktop. To resolve this, Check if the Descriptor field has an old version incompatible with the newer Flow Production Tracking Desktop version. More here

  • ERROR: “TankInitError object has no attribute” when creating a file in a specific task using the tank command in Autodesk Flow Production Tracking (formerly known as ShotGrid). Solution: Follow the instructions outlined here

  • ERROR: TankError: Cannot resolve template data for context. The solution is to create teh relevant folders by running the tank folders command. More details on this can be found here

  • ERROR: Configuration metadata file. It happens when we move manually the project configuration folder. Solution: Check that the config/core/install_location.yml and config/core/roots.yml points to the right paths.

  • ERROR: Failed to complete ‘New File’ action: Unable to resolve template fields after folder creation! This could mean there is a mismatch between your folder schema and templates.

  • Critical! Could not update PTR with folder data. Please contact support. Error details: API batch() request with index 0 failed. All requests rolled back.API create() CRUD ERROR #6: Create failed for [Attachment]: Path /Users/leonams/Documents/DEV_local/FlowPTR/storageRootFolder/sergio_22/assets/Prop/Grass doesn’t match any defined Local Storage. Solution: Please check solutions proposed here

2 Likes