Tekla.Environment.Api.Client.Console 1.0.0

Tekla Environments CLI (teklaenv)

teklaenv is a .NET global tool for automating Tekla Environment Service operations:

• Package download (including version resolution and URL-only mode)
• Package upload (with metadata pairs)
• Package definition bulk create/update from CSV
• Metadata definition bulk create from CSV
• Permission create/delete/report on package definitions
• API key operations (create, rotate, list)

The tool command is:

teklaenv

Install

From NuGet.org (after you publish)

dotnet tool install --global Tekla.Environment.Api.Client.Console

Update to the latest published version:

dotnet tool update --global Tekla.Environment.Api.Client.Console

Uninstall:

dotnet tool uninstall --global Tekla.Environment.Api.Client.Console

From a local .nupkg (pre-publish validation)

dotnet tool install --global Tekla.Environment.Api.Client.Console --add-source .\BuildDrop\ApiNugetPackageOutput

Quick start

List commands:

teklaenv --help

List options for one command:

teklaenv DownloadPackage --help
teklaenv UploadPackage --help

Default API URL is:

https://cloud.api.trimble.com/tekla/environments/v1

Override with -u/--apiurl for dev/staging or private deployments.

Authentication model

Which commands use API key, token, or both

• Commands that accept API key (-k): DownloadPackage, UploadPackage
• Commands that do not accept API key: CreatePackageDefinition, CreateMetadataDefinition, CreatePermission, DeletePermission, ReportPermissions, apikeys
• API key only mode: DownloadPackage, UploadPackage

Package operations (DownloadPackage, UploadPackage)

These support exactly one of these auth modes:

• User token only: supported (-t)
• API key only: supported (-k)

-t and -k are mutually exclusive.

Important: --trimbleIdToken must be a Trimble Id access token (not an OIDC identity token). In API key mode, the CLI exchanges the key at POST /auth/token, then calls package endpoints with the returned bearer token + session token.

Non-package operations

These are token-based operations and do not use -k:

• CreatePackageDefinition (-t)
• CreateMetadataDefinition (-t)
• CreatePermission (-t)
• DeletePermission (-t)
• ReportPermissions (-t)
• apikeys service operations such as --type key and --type client (--token)

Use apikeys to create/list/rotate API keys and support migration scenarios.

Feature reference

Download package

Downloads a package to disk, with cache-by-output-folder behavior.

User token mode:

teklaenv DownloadPackage `
  -t <trimbleIdAccessToken> `
  -i <packageDefinitionId> `
  -v latest `
  -o C:\temp\packages

API key mode:

teklaenv DownloadPackage `
  -k <apiKey> `
  -i <packageDefinitionId> `
  -v latest `
  -o C:\temp\packages

Resolve and print only the pre-signed download URL:

teklaenv DownloadPackage -k <apiKey> -i <packageDefinitionId> -v 1.0.0 --urlOnly

Resolve latest version inside a NuGet-style range:

teklaenv DownloadPackage `
  -k <apiKey> `
  -i <packageDefinitionId> `
  --versionConstraint "[2024.0.0, 2025.0.0)"

Notes:

• -v accepts explicit version, latest, or can be omitted.
• -o folder also acts as download cache.
• In API key mode, token exchange is handled automatically by the CLI.

Upload package

Uploads a local package file to one or more service-provided upload URLs.

User token mode:

teklaenv UploadPackage `
  -t <trimbleIdAccessToken> `
  -i <packageDefinitionId> `
  -v 1.0.0 `
  -f C:\temp\package.zip `
  -m region=emea

API key mode:

teklaenv UploadPackage `
  -k <apiKey> `
  -i <packageDefinitionId> `
  -v 1.0.0 `
  -f C:\temp\package.zip `
  -m region=emea `
  -m releaseChannel=official

Metadata format is <metadataDefinitionId>=<value>. Repeat -m for multiple entries.

Create package definitions from CSV

Creates or updates package definitions from a semicolon-separated file.

teklaenv CreatePackageDefinition -t <trimbleIdAccessToken> -d C:\data\package-definitions.csv

Update existing definitions instead of create:

teklaenv CreatePackageDefinition -t <trimbleIdAccessToken> -d C:\data\package-definitions.csv --patch

Expected header:

EnvironmentId;Name;Description;BlobId;Metadata;OrganizationId;ThumbnailPath

ThumbnailPath is optional and can be absolute or relative to the CSV file folder.

Metadata format in each row:

metadataId1=value1|metadataId2=value2

Create metadata definitions from CSV

Creates metadata definitions in bulk:

teklaenv CreateMetadataDefinition -t <trimbleIdAccessToken> -d C:\data\metadata-definitions.csv

Expected header:

MetadataDefinitionId;Name;Description;Type;AllowedValues;MultipleValuesAllowed;ParentId

AllowedValues separator is |. MultipleValuesAllowed should be true or false.

Manage permissions

Create permission for package definition:

teklaenv CreatePermission `
  -t <trimbleIdAccessToken> `
  -i <packageDefinitionId> `
  --permission Use `
  --versionconstraints "+:[0.0.0, 2026.2099.0]"

Scope permission to one group:

teklaenv CreatePermission -t <trimbleIdAccessToken> -i <packageDefinitionId> --groupid <groupId> --permission Use

Delete permission for one organization:

teklaenv DeletePermission -t <trimbleIdAccessToken> -i <packageDefinitionId> --orgid <organizationId>

List permissions:

teklaenv ReportPermissions -t <trimbleIdAccessToken> -i <packageDefinitionId>

API key operations

Create revocable key with 6 month lifetime:

teklaenv apikeys --type key --token <trimbleIdAccessToken> --expire 6m --label "ci pipeline"

Rotate an existing key:

teklaenv apikeys --type key --token <trimbleIdAccessToken> --rotate <keyId>

List keys:

teklaenv apikeys --type key --token <trimbleIdAccessToken> --list

Supported --expire values: 1d, 1m, 3m, 6m, 12m.

Exit codes

• 0 success
• non-zero failure

For diagnostics, re-run with command-specific --help and validate required options.

Troubleshooting

• teklaenv not found: add %USERPROFILE%\.dotnet\tools to PATH, then open a new shell.
• Authentication failures: confirm access token type and target --apiurl.
• Version lookup issues: pass explicit -v or refine --versionConstraint.
• CSV import failures: verify separator is ; and required columns are present.