Tau CLI¶

This page is a practical, end-to-end guide to using tau without interactive prompts and with production-safe defaults.

If you want deep resource-specific behavior, use the Development pages as the canonical reference. This page focuses on command flow, command families, and high-signal usage patterns.

Install and verify¶

npm i -g @taubyte/cli
tau --version
tau --help

Core mental model¶

A project has two repositories managed by Tau:
config repository (tb_config_<project>)
code repository (tb_code_<project>)
You usually work in this order:
authenticate
select cloud/universe + project
create or edit resources
push config
push code
check build/logs

Authentication and profile management¶

Create a profile¶

tau login --new my_profile --set-default

tau login --new my_profile --provider github --token "<TOKEN>" --set-default

Switch profile¶

tau login my_profile
tau whoami

Context and selection¶

See current context¶

tau current

Select cloud (remote)¶

tau select cloud --fqdn cloud.taubyte.com

Select project¶

tau select project my_project
tau current

Project lifecycle¶

Create project (non-interactive)¶

tau new project my_project \
  --description "Main product project" \
  --private \
  --no-embed-token \
  --yes

Clone project repositories¶

tau clone project my_project --branch main --no-embed-token --yes

Pull and push¶

tau pull project
tau push project --config-only --message "update config"
tau push project --code-only --message "update code"

Resource command families¶

Most resources follow this shape:

tau new <resource> <name> [flags]
tau edit <resource> <name> [flags]
tau delete <resource> <name>
tau list <resource_plural>

Use tau --help and tau <command> --help to view full flags in your installed version.

Create resources quickly (high-value templates)¶

Application¶

tau new application app_main --description "Main app" --yes

HTTP function¶

Important: - use one function per method+path - do not combine methods in one function

tau new function get_notes \
  --description "List notes" \
  --type http \
  --method GET \
  --paths /notes \
  --source app_main/functions/get_notes \
  --template empty \
  --language Go \
  --timeout 30s \
  --yes

Website¶

tau new website docs_site \
  --description "Documentation website" \
  --template empty \
  --domains docs.example.com \
  --paths / \
  --provider github \
  --generate-repository \
  --no-private \
  --branch main \
  --no-embed-token \
  --yes

Database¶

tau new database notes_db \
  --description "Notes data" \
  --match notes \
  --min 1 \
  --max 1 \
  --size 1GB \
  --yes

Storage¶

tau new storage uploads_store \
  --description "User uploads" \
  --match uploads \
  --bucket Object \
  --size 10GB \
  --versioning \
  --yes

Messaging¶

tau new messaging events_channel \
  --description "App event bus" \
  --match events \
  --mqtt \
  --web-socket \
  --yes

Domain¶

tau new domain app_domain \
  --description "Public app domain" \
  --fqdn app.example.com \
  --cert-type le \
  --yes

Library¶

tau new library shared_sdk \
  --description "Shared app code" \
  --template empty \
  --provider github \
  --generate-repository \
  --private \
  --branch main \
  --no-embed-token \
  --yes

Production-safe workflow¶

Use this exact sequence after resource changes:

Push config first:

tau push project --config-only --message "resource config updates"

Then push code:

tau push project --code-only --message "function and website code updates"

Verify builds:

tau query builds --since 24h
tau query logs --jid "<JOB_ID>"

Dream/local workflow¶

dream is the local cloud runtime. Use it with tau to test full workflows before remote deployment.

1) Install and start¶

npm i -g @taubyte/dream
dream status
dream start

2) Create/select universe¶

dream status universe default
dream new universe default
dream select universe default

3) Point Tau to local context¶

tau select cloud --universe default
tau current

4) Work normally¶

Use the same tau new, tau edit, tau push, tau query flow you use remotely.

Non-interactive patterns you should always use¶

Prefer explicit boolean flags:
--no-embed-token instead of interactive prompts
--private or --no-private explicitly for repo visibility
Always pass --yes when scripting resource creation.
Always pass --branch main on clone operations.
Avoid prompt-only flows in CI.

Windows notes¶

For some path-based flags in Git Bash/MSYS, disable path conversion:

MSYS_NO_PATHCONV=1 tau new function ...

Keep command examples in shell-compatible quoting.

Troubleshooting¶

`project is not selected` or wrong context¶

tau current
tau select project my_project
tau current

Build fails after push¶

tau query builds --since 24h
tau query logs --jid "<JOB_ID>"

Check for: - invalid function method/path setup - wrong source path - missing .taubyte metadata in function/website folders - compile/runtime errors in function code

Dream/local commands fail¶

dream status
dream start
dream status universe default

If Docker is not running, start Docker Desktop first, then retry.

Full potential checklist¶

Keep one project per product boundary.
Group resources by application.
Keep one HTTP function per method+path.
Reuse code through libraries.
Use matcher values consistently for data resources.
Push config before code when infra changes.
Use local Dream for integration testing.
Monitor every deployment with tau query builds and tau query logs.

Command discovery map¶

Use these help pages directly in your terminal:

tau --help
tau new --help
tau edit --help
tau delete --help
tau list --help
tau clone --help
tau pull --help
tau push --help
tau query --help
tau select --help
tau current --help

For complete local cloud operations, see Dream CLI.