GrowToward Quick Start

Complete the installation guide before continuing. It covers the CLI, account creation, and sign-in.

Once the CLI is installed and authenticated, list your instances:

gt instance list

Every account starts with <your username>_global and work. Those instances have special roles, so create a separate instance for ordinary project tasks. This example calls it “Hello World.”

gt instance create name="Hello World"

The new instance has the handle hello_world. Open its GrowToward shell:

gt shell hello_world

The shell opens on a placeholder “miscellaneous” task. Type a task name and press Enter, then press Enter again to move to the new task. The placeholder disappears automatically, leaving your task first on the to-do list.

Time tracking is on by default. For initial exploration, you may want to enter am twice to turn it off.

Enter /h to see the full list of commands.

Enter q to quit the shell.

For more shell guidance, see section 4 below.

A GrowToward instance gives one area of work its own tasks, planning model, and shell.

Vectors

Vectors represent long-running work or outcomes. A vector can advance other vectors through weighted components.

A vector can also have ingredients. A vector with ingredients acts as a recipe.

Some or all ingredient weights can be selected by a zero-sum allocator based on the Colonel Blotto problem from game theory. A recipe managed this way is a contest.

Each instance has an instance recipe representing the long-term purpose of its tasks. Leaf vectors in that recipe's ingredient tree are end vectors, or ends.

Every vector maintains a current weighted mapping to the ends. That mapping aggregates every path from the vector through the ingredient graph and expresses its contribution to the instance's purpose.

Tasks can have weighted vector components too, so their end mappings are computed in the same way.

Tasks and the opportunity chain

Every task has a name, duration, and priority. A task can also carry a cost, due date, and other planning details.

A task's priority can be low, medium, high, next, or urgent. High-priority tasks are selected five times as often as medium-priority tasks, and medium-priority tasks five times as often as low-priority tasks. “Next” tasks fill the allotted time; urgent tasks are selected unconditionally. By default, the goal generator weighs progress toward ends alongside priority, while giving special treatment to next and urgent tasks.

A task can have other tasks as steps, forming an ordered list of prerequisites.

A task can also have opportunities. At least one opportunity must be completed before the task becomes available, and each opportunity can have a user-defined probability of unlocking it.

The forest of steps and selected opportunities beneath a generated to-do list is its opportunity chain. The gt shell helps you navigate and revise that chain.

For work that repeats on a schedule, create a recurring task with an RRULE.

Using the API from the CLI

A typical API call has the form gt <resource type> <endpoint> <pk?> <arg?>=....

The resource types are: user, instance, vector, task, recurring-task, logs, subcontest-group, opposition, document

Run gt <resource type> without an endpoint to list the operations available for that resource.

These lists omit operations the server does not expose. For example, vectors can be listed and retrieved directly, but gt vector create is not available.

Use instance update-vectors for structured, alias-keyed graph updates. For GT files, use instance import-gt, instance load-document, or document instantiate.

gt instance update-vectors <instance-id> component_map=@vectors.yaml
gt instance import-gt <instance-id> materialization=patch text=@plan.gt
gt document instantiate <document-id> materialization=replace

Filters support Django-style double-underscore joins. For example: gt vector filter instance__handle=my_instance aliases__alias="my vec"

The Python client

Client classes include:

• UserClient for user/account endpoints
• InstanceClient for instances/workspaces
• DocumentClient for documents
• VectorClient for vectors
• ContestClient for contests
• TaskClient for tasks
• RecurringTaskClient for recurring tasks
• LogClient for logs
• GoalParametersClient for goal parameters
• APIKeyClient for API key operations
• OppositionClient for oppositions
• SubcontestGroupClient for subcontest groups
• ReminderClient for reminders

Here's a small python script leveraging the API:

import growtoward as gt

user_client = gt.UserClient()
my_uu = user_client.whoami()['uu']
print(f'my uu: {my_uu}')

instance_client = gt.InstanceClient()
work_instance = instance_client.filter(handle='work')[0]
instance_client.update_vectors(
    work_instance['id'],
    component_map={'important_work': {'customer_value': 1}},
)
todo_list = instance_client.get_todo_list(work_instance['id'])
print()
print('Current to-do list in my work instance:')
for t in todo_list:
    print(f"- {t['name']}")

Launch the shell:
    gt shell <instance handle>

Create a 5-minute urgent task:
    this is my new task 5 !!

Create a $5 high-priority task:
    this is my new task $5 hh

Create a medium-priority task:
    this is my new task mm

Create a task at step 4 under this task:
    /as 4::this is my new task

Delete the task at step 4 under this task:
    @.4 d

Regenerate the to-do list:
    /wg

Go to the immediate step under this task:
    @now

Go to the last step of the parent task of the immediate step under this task:
    @now..-1

Go to the 5th task's second-to-last step in another instance:
    @other_instance.5.-2

Show all steps under the current task:
    /show .

Show all steps under the current task in a prompt-ready format:
    /show prompt

Set the current task to recur every Saturday:
    /rr FREQ=WEEKLY;BYDAY=SA

Create a low-priority task in a separate instance without leaving the current task:
    @other_instance new task ll

Add an existing vector as a component of the current task:
    /push components::my vector::0.6

Change the current task's name:
    /push name::new name