Using the tn command line

tn is terranode's command-line client for working with organizations, catalogs, uploads, and data sources from a terminal or script.

Early preview

tn is new and not yet published anywhere you can pip install it from directly. Ask your terranode contact for access while that is being set up.

Signing in

tn auth login

You'll be asked for your email and password. tn stores its own command-line token locally in ~/.config/tn/config.json so you don't have to log in again for every command. This is separate from your browser session in the web app.

If you belong to more than one organization, pick a default organization ref:

tn config set-org acme

tn orgs list shows the organizations you belong to, including each organization's slug and id. tn auth whoami shows who you are and, for each organization, what you are allowed to do there. See Roles and permissions.

Resource refs

A ref is the value you type to identify something. For readable resources, a ref can be either the stable UUID id or the human-friendly slug shown in tn output.

Refs accepted by tn today:

• Organization ref: organization id or slug.
• Catalog ref: catalog id or slug inside the selected organization.
• Data source ref: data source id or slug inside a catalog.
• Upload id: uploads are not named, so uploads stay id-only.
• API key id: API keys stay id-only.

Slugs are easier to type, but they can be renamed. Use ids for long-lived scripts when stability matters.

Working with catalogs

tn catalogs list
tn catalogs create --name "Field boundaries" --visibility private
tn catalogs get field-boundaries
tn catalogs update field-boundaries --name "New name"
tn catalogs delete field-boundaries

Add --json after tn to get machine-readable output instead of a table:

tn --json catalogs list

Uploading data into a catalog

tn uploads create field-boundaries ./roads.geojson --wait

This uploads the file and, with --wait, blocks until terranode has finished turning it into one or more data sources. Drop --wait to return immediately and check later:

tn uploads list field-boundaries
tn uploads get field-boundaries <upload-id>
tn datasources list field-boundaries
tn datasources get field-boundaries roads

Data sources themselves aren't created or edited directly. They are created when an upload finishes processing.

Managing your team

Everyone can list the members of their organization. Everything else here needs the owner role. People are identified by email address.

tn orgs members list
tn orgs members set-role ana@example.com editor
tn orgs members remove ana@example.com

set-role takes owner, editor or field. remove takes the person out of the organization but keeps the record, and inviting the same address again brings them back. The organization always keeps at least one active owner, so changing or removing the last one is refused.

To invite people, give one or more addresses and a role that applies to all of them:

tn orgs invitations create ana@example.com bob@example.com --role field
tn orgs invitations list
tn orgs invitations resend ana@example.com
tn orgs invitations revoke ana@example.com

create prints one row per address. An address that can't be invited, such as someone who already belongs to the organization, doesn't stop the others, and the command exits with an error if any address failed. list shows invitations that are still open. An invitation that has expired is not listed: invite the same address again to renew it.

Automating without your password

If you want a script, CI pipeline, or server to use tn without your personal login, create an API key instead. You need to be an organization owner.

tn orgs api-keys create --name "ci-pipeline" --role editor

This mints a long-lived credential and, by default, switches this machine to use it. If the key is meant for somewhere else, add --mint-only:

tn orgs api-keys create --name "ci-pipeline" --role editor --mint-only

Wherever the key ends up, set it as TN_TOKEN in that environment:

export TN_TOKEN="<the key you were given>"
export TN_ORG="acme"

List or revoke keys for your organization at any time:

tn orgs api-keys list
tn orgs api-keys revoke <key-id>

See the Glossary for terms like catalog and organization used throughout this page.