Passing Command Line Arguments To Blender Python Scripts

What are Command Line Arguments?

Command line arguments, often shortened to command line args or CLI args, are additional inputs that can be passed to a Python script when it is executed from the command line interface. They allow customizable data to be fed into the script each time it is run, without needing to directly edit the code.

Command line arguments make scripts more flexible, configurable, and automated. Instead of hard-coding data like file paths or parameter values into a script, they can be passed in as args instead. The script then programmatically accesses these args and uses them in its operations.

In Blender, Python scripts can access any command line args passed in using the sys.argv list. This contains all args as strings, allowing them to be processed or converted as needed. By leveraging command line args, Blender Python scripts can have dynamic runtime behavior.

Accessing Command Line Arguments in Blender

Within a Blender Python script, the sys.argv list contains any command line arguments provided when executing the script. The first item, sys.argv[0], is always the path to the script file itself. Any additional args are then contained in subsequent indices of sys.argv.

Here is some sample code to print out all command line args in a Python script:


import sys

for arg in sys.argv:
    print(arg)

And accessing a single command line argument individually:


import sys

arg1 = sys.argv[1] 
print(arg1)

In this case sys.argv[1] would contain the first additional argument passed to the script at launch. Additional args can be accessed through further indices of the list.

Using Arguments in Blender Scripts

There are many different ways command line arguments can be leveraged in Blender Python scripts. Some examples include:

Passing in multiple files or folders to process
Specifying parameter values like width, height etc
Selecting different modes or operations
Setting IDs, names, or other identifying data

Arguments can be passed in when executing a script from the command line or configured in the properties window under the Scripting tab. Multiple args are segmented by spaces when passed to a script:


my_script.py firstArg secondArg thirdArg

And each can be accessed through sys.argv indices:

 
first = sys.argv[1]
second = sys.argv[2]  
third = sys.argv[3]

This data can then used throughout the script to control its operations and behavior.

Common Use Cases

Some typical applications which use command line arguments in Blender include:

Procedural Asset Generation

Procedural tools often allow customization through args like size, subdivision level, texture scale, etc. These parameters can be changed to generate unique assets each script execution.

Batch Operations

Arguments allow easy passing of groups of files or folders to operate on. Things like modifiers, materials, rigging can be applied in batch to multiple objects.

Script Control

Command line args provide a simple interface for controlling logic flow in scripts. Operations, modes, algorithms can all be changed via args without direct code edits.

Best Practices

To most effectively use command line arguments in Blender Python, here are some best practices:

Argument Parsing

Check argument length to ensure the expected number are passed. Also validate their data types – convert strings to ints/floats as needed.

Error Handling

Account for missing arguments or invalid data passed. Catch errors and provide useful information to help debug issues.

Argparse Module

For more advanced argument functionality, use the argparse module. This allows options, flags, help text and more robust handling of args.

Example Scripts

Here are some examples demonstrating command line argument usage in Blender:

Asset Generation


# procedural_asset.py

import sys
import bpy

verts = int(sys.argv[1])
subdiv = int(sys.argv[2]) 

# Generate procedural mesh using args
obj = bpy.data.objects.new(f'MyObject_{verts}_{subdiv}') 

...

Called via: procedural_asset.py 64 3

Batch Rename

  
# batch_rename.py 

import os
import sys

path = sys.argv[1]
prefix = sys.argv[2]

for file in os.listdir(path):
    os.rename(file, f'{prefix}_{file}')

print('Renaming complete!')

Called via: batch_rename.py /scene/objects obj

Mode Control


# process_items.py

import sys 

mode = sys.argv[1]  

if mode == 'VERTEX':
   # Vertex processing logic
elif mode == 'FACE':
   # Face processing logic
   
...

Called via: process_items.py VERTEX

Frequently Asked Questions

How do I pass command line args in Blender?

In the Properties editor Window, under the Scripting tab, arguments can be defined then accessed with sys.argv in the Python code. They can also be passed when executing a script from the command line or terminal.

Where do args show up in a Python script?

The sys.argv list contains any command line args. sys.argv[0] is the script name, and args start at sys.argv[1] and beyond.

What is the best way to handle multiple args?

Check the length of sys.argv to ensure the expected number exist. Also validate data types, convert them as necessary, and catch any potential errors.

Can I use command line args in an addon?

Yes, addons can also access external args through sys.argv when activated. Access them the same as in a standalone Python script.

Additional Resources

To learn more about leveraging command line arguments in Blender and Python scripts, check out these useful resources: