Your First Sync

Welcome to your first step with Tungsten. By the end of this guide, you will have your project configured, your authentication secure, and your first asset safely synced to your Roblox place.

Initializing your Project

Tungsten is designed to be “zero-config” where possible, but it needs to know where your assets live and which Roblox target (User or Group) you are syncing to.

Open your terminal, navigate to your project directory, and run:

Terminal

tungsten init

What just happened?

Running init scanned your directory and generated a tungsten.toml configuration file. This file is the “brain” of your project.

Configuring your Project

Open your newly created tungsten.toml in your preferred code editor. You need to define your creator so Tungsten knows where your assets are going.

tungsten.toml

[creator]
# Set your User ID or Group ID here, and specify the type
type = "user"  # or "group"
id = 12345678

Authenticating with Roblox

Tungsten requires an API key with Asset Write and Read permissions to function. You have three ways to provide this key, depending on your security preference:

Option A: Environment Variable (Recommended for CI/CD)

Set the variable globally in your system or terminal session:

Terminal

export TUNGSTEN_GLOBAL_APIKEY="your-api-key-here"

Option B: Local .env File

Create a file named .env in your project root:

• Directoryassets

  • …
• tungsten.toml
• .env

.env

TUNGSTEN_API_KEY=your-api-key-here

Danger

Never commit your .env file or API keys to GitHub. Ensure your .gitignore includes .env.

Option C: The CLI Flag

If you want to use a key only for a specific run, pass it directly in your command:

Terminal

tungsten sync cloud --api-key your-api-key-here

Placing your Assets

Now, place your assets in the folders defined in your inputs. For example, with the default config:

tungsten.toml

[inputs.assets]
path = "assets/**/*"
output_path = "src/Assets.luau"
type = "decal"

Drop your files in assets/:

• Directoryassets/

  • play.png
  • monster.png
  • goog.svg

Notice

Make sure the formats of the assets reflect the accepted formats for the asset type.

Tungsten will automatically pick up these files on the next sync. You can create a .tmeta file next to any asset later if you need custom names or descriptions, but for now the defaults will handle the heavy lifting.

The Sync

Now that your config is set and your assets are ready, it’s time to push to the cloud.

Run the following command:

Terminal

tungsten sync cloud

You should see Tungsten spring into action:

1. It validates your tungsten.toml.
2. It authenticates using your provided API key.
3. It detects the new files in your assets/ folder.
4. It uploads the assets and returns the asset IDs.

Congratulations! You have successfully synced your first assets. You can now use the returned IDs in your Roblox projects.