Command nodes

Command nodes let you customize a string of actions which you can run via buttons or via the command line. There are Tana commands that extend our command line, and AI commands that extend OpenAI's API

Overview

Command nodes are a way to create your own custom commands using Tana's extensive command library. It lets you set up a string of automated actions inside Tana, and then executing them via 🔘 buttons or ⌨️ the command line.

Commands can be as simple as adding tags, moving the target node or changing the values of its fields. It can also be used in combination with AI, API calls or complex strings of commands.

Command nodes are easier to understand if you're already comfortable with using the command line and the search query.

Basics

  • There are three essential elements to creating custom commands: the command node that is a container for the command, the commands that represent the actions you want to do, and the parameters that are the settings for the commands
  • To create a custom command node, run Cmd/Ctrl+K > Convert to command node on an empty node.
  • To configure what the command node does, add commands as child nodes to it. To get a list of all available commands you can add, use @.
  • Each command can receive certain parameters (represented as system fields), listed in the description. The ones that are starred are required. Add the necessary parameter fields to the command (hit > to create a field, then the name of the parameter), and fill it with the necessary field value.
  • If there are multiple commands in the command node, they are executed in the order that they're listed from the top.
  • You cannot add the same command twice. To repeat a command, wrap it in another command node and add that to the list.
  • Command nodes appear as buttons attached to nodes, supertag instances, or fields. They also appear in the command line.
  • You can control when/where a command appears by using node filter and node context parameters on the main command node.
  • You can find all commands in your workspaces by writing the keyword operator IS_COMMAND in the search node.

Documentation

Create a command node

To create a command node, on any node go Cmd/Ctrl+K > Convert to command node:

The icon of the node will change. Give the command node a name, which will appear on command buttons, and on the command line.

Set up commands and parameters

Commands

To configure the command node, select the commands you want using @. This gives you a filtered list of all available commands, including Tana commands, AI commands and custom commands you've defined previously.

Tana commands include:

  • Set field value tells the system to do the _action_ of setting a field underneath your node—same way we do it ourselves—and then, optionally, filling that field with a specific value.
  • Insert a cloned copy of a node tells the system to do the action of copying another node (that you specify inside the command) and bringing a clone of that node into the context in which you're working.
  • Add tag adds a tag to your node, and Remove tag takes one away.

See All Tana commands and All AI commands for a full list of options.

Parameters

Each command has a set of parameters you use to configure it. To add a parameter to a command, add any of the listed parameters as a field under the command. Parameters with a star are required.

Using the example of the Move node command, you'll find these settings:

  • Target node: Let's you instruct the action where to send the moved node.
  • Remove reference after moving node: Let's you decide whether you want there to be a reference to your moved node at the current location, or not.
  • Node filter/Node context: These settings are available on all commands and let you specify which nodes will run your command, in various ways.

Using the Move node-command and these settings, you could, for instance, make a command that

  • Sends a node to your team workspace and
  • Removes the reference from your workspace

Combining this with Add tag and Set field values, you could

  1. create a new #project (Add tag)
  2. assign it to your teammate Brage (Set field value)
  3. set status to Active (Set field value) and
  4. send it to your shared workspace Viral Content (Move node)

all with one button click.

Access commands

Commands in the command line

Once you've configured your command node, it will appear in the command line (Cmd/Ctrl+K) as another command you can access alongside the default commands.

Commands as buttons

Once you've configured your command node, you can use it to make buttons appear in any node. With your caret on target node, go to the command line Cmd/Ctrl+K > Configure node to open the node configuration. Add your command node in the Commands field.

You can also add a command node to a supertag or field, see the Advanced section of the supertag/field configuration panel. The command will appear alongside the tagged node or field.

Node filter

Using the parameter Node Filter, you can use search query language to control which nodes the command can be run on.

For instance, if you made a command specifically to run on your #standup tag and no other tag or node, you can add this:

>Node filter: #standup

An excluded node will not display the command, neither from the command line nor as a button.

Finding all commands

You can find all commands in your workspaces by creating a search node and using the keyword operator IS COMMAND. Scope it down to a workspace to only find commands from there.

All Tana commands

Insert a cloned copy of a node

Can be used to emulate template behaviour, add a new time log entry to a time log etc

Insert relative date

System command that inserts a date using the relative date string.

Move node

System command that moves a node

Add tags

System command for adding a tag to a node.

Remove tags

System command for removing a tag from a node.

Set field values

System command for setting field values to a field.

Set field values for all children

System command for setting field values to a field applied to all children. Example: Set all children to "status deployed" for a release process.

Remove fields

Removes the specified field

Set done status

Sets the done status of a node to a particular setting

Set view definition

Takes the same information that is stored as a custom view on a node - can be used to configure which columns are shown, sorting, filtering, grouping etc.

Set view type

Can set node to table, cards, list, tabs, calendar view.

Show alert

Displays a user alert

Ask for user confirmation

Displays a user confirm command, and halts execution if user does not confirm

Run commands in parallel

Takes a list of commands as input, and runs them in parallel (default is sequential)

Run a command line command

Let's you run any command from the command line. Does not work well with multi-stage prompts

Run commands on all children

Let's you run a command on all children.

All AI Commands

Ask AI

Can be run on a single node, a single field, or can be configured with prompts, batch processing, temperature etc.

Make API request

Making an API request involves specifying the API endpoint, choosing the appropriate HTTP method, providing any necessary headers or authentication, and handling the response from the API. This process allows different software systems to exchange data and functionality seamlessly.

Generate image(s) with DALL-E

Returns an AI-generated image using DALL-E.

Cluster children with embeddings

Takes a list of children, gets embeddings, and does unsupervised clustering. Given that you have to manually specify number of clusters, this is more of an experiment until we have server-side processing.

Fill in all empty AI fields

System command that uses the field's context to fill empty AI fields

Transcribe audio

Sends an audio file to WhisperAI and returns a transcription.

Autotag

Add tags using GPT interpretation

All parameters

Prompt

  • Description: Prompt expression - same syntax as title expression, but can be multiline. ${sys:context} gives context of node and children.
  • Source: OpenAI

Node filter

  • Description: Search query to filter nodes that this command can be run on
  • Source: Tana

Node context

  • Description: Node context for commands - defaults to node the command is run on
  • Source: Tana

Field dependencies

  • Description: References to other fields on the same node. If any of these fields are empty, and have AI turned on, then their AI prompts will be run before evaluating this command.
  • Source: Tana

Target node

  • Description: Defines what Tana object to insert the result into. Can be a reference to a template node, or a field reference
  • Source: Tana

Temperature

  • Description: What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. OpenAI generally recommends altering this or top_p but not both. Defaults to 0.
  • Source: OpenAI

Top P

  • Description: An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. OpenAI generally recommends altering this or temperature but not both. Defaults to 1.
  • Source: OpenAI

Suffix

  • Description: A string that will be appended to the end of the text.
  • Source: OpenAI

Best of

  • Description: Generates best_of completions server-side and returns the "best" (the one with the highest log probability per token). When used with n, best_of controls the number of candidate completions and n specifies how many to return – best_of must be greater than n.
  • Source: OpenAI

Max tokens

  • Description: The maximum number of tokens to generate. Will be capped at maximum given prompt length. Defaults to maximum.
  • Source: OpenAI

Model to use

  • Description: Defaults to text-davinci-003 or the most capable model.
  • Source: OpenAI

Stop sequences

  • Description: Up to 4 sequences where the API will stop generating further tokens. The returned text will not contain the stop sequence. One sequence on each node.
  • Source: OpenAI

Presence penalty

  • Description: Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. Defaults to 0.
  • Source: OpenAI

Frequency penalty

  • Description: Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. Defaults to 0.
  • Source: OpenAI

Insert output strategy

  • Description: Default is adding as a child
  • Source: OpenAI

Combination prompt

  • Description: After running the normal prompt over all of the context, this prompt will be run with ${sys:context} set to the concatenated output.
  • Source: OpenAI

Batch prompt context

  • Description: The presence of this field enables splitting up a long context into multiple prompts, which can optionally be combined with the Combination prompt. The field ${sys:context} is determined by the dropdown options, or by a reference to a field or a node.
  • Source: OpenAI

Fill context window percentage

  • Description: The context window size includes both the prompt and the response. This parameter takes a number from 0 to 1, and determines the percentage of the context window that the prompt is allowed to fill - both for indidual and batched prompts. The default is 0.5, which means that the prompt and response are equal in size.
  • Source: OpenAI

URL

  • Description: URL, processed using title expressions
  • Source: Tana

Insert output strategy

  • Description: Default is adding as a child (except in fields, where default is replace)
  • Source: OpenAI

Payload

  • Description: Payload type
  • Source: OpenAI

API method

  • Description: Defaults to GET
  • Source: Tana

Parse results

  • Description: Defaults to no parsing (raw)
  • Source: Tana

Authorization header

  • Description: For authentication (for example "Bearer ....")
  • Source: Tana

Headers

  • Description: API headers, must start with a word and a colon, like "Authorization: ..."
  • Source: OpenAI

Avoid using proxy

  • Description: For local sites, or where you know there is no CORS issue
  • Source: Tana

Tags

  • Description: Define supertags
  • Source: Tana

Image size

  • Description: The size of the generated images. Must be one of 256x256, 512x512, or 1024x1024 for dall-e-2. Must be one of 1024x1024, 1792x1024, or 1024x1792 for dall-e-3 models.
  • Source: OpenAI

Number of images to generate

  • Description: The number of images to generate. Must be between 1 and 10. For dall-e-3, only n=1 is supported.
  • Source: OpenAI

Metaprompt to enhance prompt with GPT-3

  • Description: n/a
  • Source: Tana

Number of groups

  • Description: Defaults to 3
  • Source: OpenAI

Transcription Language

  • Description: The language of the input audio. Supplying the input language in ISO-639-1 format will improve accuracy and latency.
  • Source: OpenAI

View definition

  • Description: View definition to apply to node
  • Source: Tana

View type

  • Description: Set view type by picking from dropdown.
  • Source: Tana

Fields to set

  • Description: Fields to set, and optionally values
  • Source: Tana

Commands

  • Description: Commands to execute
  • Source: Tana

Tag candidates

  • Description: Define supertags that become candidates
  • Source: Tana

Fields to remove

  • Description: Define fields that, if present, will be removed.
  • Source: Tana

Move node target

  • Description: Define node to be moved. Reference to a specific node, field or a dropdown option
  • Source: Tana

Remove reference after moving node

  • Description: Will remove the reference after moving node
  • Source: Tana

Move original node

  • Description: By default, if you run the command on a reference, the reference will be moved. This option can force the original node to be moved.
  • Source: Tana

Done status to set

  • Description: Gives you done state options to set. There are four options to choose from:
    • Node has no checkbox
    • Done
    • Not done
    • Toggle done status
  • Source: Tana

Command to run

  • Description: Write out the commands you want to run.
    • If you're uncertain about how a command is written out, navigate to it through the command line, create a custom shortcut, and go to Settings > Private keyboard shortcuts to the shortcut you just made and expand it. You'll find the command written out in a node.
  • Source: Tana

Look for children in field

  • Description: Looks for children in a specific field, instead of the node. Add reference to field definition.
  • Source: Tana

Relative date string

  • Description: Write out a date string like this week, in two months, etc. Interpreted with prompt expressions.
  • Source: Tana

Reference date

  • Description: Either a date, or use Lookup field to reference a field. If reference date is May 1, and relative date is in two weeks, the output will be May 15th.
  • Source: Tana

Date/time granularity

  • Description: Allows you to specify the granularity of the date object. Use the dropdown to set year, month, week, day, hour, minute, second, or millisecond.
  • Source: Tana

Set only start or end of date

  • Description: Allows you to specify whether you want to set a Start or End date/time.
  • Source: Tana


Related release notes

  • improvedTitle expressions can now be used in openLink to build URLs ()
  • fixedFixed encoding issues in openLink command node ()
  • newThere is now a new system command node to open a link. ()
  • newNew command: Generic AI Query. Basically same thing as Ask AI, but delivered in continuous streaming style. ()
  • improvedButtons have an updated, softer look 🪶 ()
  • improvedYou can now use PARENT/GRANDPARENT for node context in command nodes. Only works in Tana, not on real grandparents. We checked. ()
  • fixedIf the Lookup field in a command parameter does not find the field on the node it is run on, the command now fails, instead of the field inserting itself. ()
  • infoRenamed "Run command on all children" to "Run commands on all children currently visible in the view", which reflects the specific behaviour of the original command that it only ran on children based on what was currently in view. It respects the current search query (which may not be saved), and filtered results. ()
  • newThere's a new command called "Run command on all children" which runs on all children based on original search queries and no filters applied. In other words, it ignores any changes to the list made by filters and/or unsaved search node queries. ()

Related FAQs

  • How can I extract the start date of a range using Commands?

    Use Insert relative date command, here's an example:

  • How do I share a supertag from my private workspace to a shared one?
    Currently, the easiest and most foolproof way to do this is to not share it but instead build the supertag, with its fields and anything else necessary for the supertag to work, from the ground up in the new space.

    That said, if you still want to move a supertag over that exists only in your private workspace, the main work is to ensure that there's nothing in the supertag that references something in your private workspace, otherwise it will appear as broken to others once it's moved.

    It's like packaging up a zip file. You can't just zip up a bunch of shortcuts, you need the real files in there or the recipient will only see broken shortcuts.

    You'll also have to remember to move over other things like field options, commands, and ensure that no saved view options contain elements from your workspace. Basically, you must ensure that nothing you're moving over from your workspace contains references from your workspace.

    To bring all nodes (except system nodes) into the supertags, fields and commands you want to move, use the command "Bring referenced node here". Alternatively, you can move each necessary node separately too if you foe example want the field definition to exist outside the supertag. But the key is that everything that is connected to what you're sending over gets sent over too, otherwise there will be missing pieces.

  • How does the "Set view definition" command work?

    There is a command called Set view definition. It can set the Group, Sort and Display settings of a node view.

    There is no good UX for this at the moment, so the instructions are not conventional nor friendly for beginners. But right now, this is one way of doing it:

    • Mock up a node that will have sample child nodes representing the data you'll be applying this command on
    • Then, create the exact view settings you want with Group, Sort and Display.
    • Go Cmd/Ctrl+K > Debug Node on the parent node and look at Views for node:
    • Clone the fields over to the command node so it looks like this:

    When you run this command on a node, this should change the view settings according to your configuration.